event.search [HTTP GET]
Search Upcoming for public events by multiple facets. If optional authentication is provided, event.search also searches private events.
Arguments
api_key (Required)
Your API application key. If you don't have one,
create one.
search_text (Optional)
The search terms to be used to look for events. To collect all events with other filters applied, do not pass a search_text.
location (Optional)
Only for use in proximity search within the US, the location parameter, if provided, will attempt to restrict search results to areas near that location. This may either be formatted as a comma-separated latitude and longitude (i.e. "37.821, -111.179"), or a fulltext location similar to the following:
- City, State
- City, State, Zip
- Zip
- Street, City, State
- Street, City, State, Zip
- Street, Zip
Any search that uses the location parameter will add the additional data elements "distance" and "distance_units" to the result set.
radius (mi) (Optional, Default: 50mi., Max: 100mi.)
If location is specified, then event.search will look for a radius parameter. Otherwise, it will use 50mi. as the radius of the search.
place_id (Optional)
An string ID like 'kH8dL0ubBZrvX_YZ', denoting a specific named geographical area. These can be seen in Upcoming 'place' URLs such as <
http://upcoming.yahoo.com/place/kH8dLOubBZRvX_YZ>, denoting the city of San Francisco, California, USA.
Using a Place ID yields events from the exact boundaries of the place, and is not affected by the
radius parameter. Eventually, Place IDs will replace the
country_id,
state_id, and
metro_id parameters used below. However, those parameters are not deprecated yet.
country_id (Numeric, Optional)
The country_id of the event, used to narrow down the responses. To get a country_id, try the metro.getCountryList function.
state_id (Numeric, Optional)
The state_id of the event, used to narrow down the responses. To get a state_id, try the metro.getStateList function.
metro_id (Numeric, Optional)
The metro_id of the event, used to narrow down the responses. To get a metro_id, try the metro.getList function.
venue_id (Numeric, Optional)
A venue_id to search within. To get a venue_id, try the venue.* series of functions.
woeid (Optional)
The WOEID of the place to which search results will be restricted.
category_id (CSV Numeric, Optional)
A category_id integer or comma-separated list of category ids to search within. To get a category_id, try the category.getList function.
min_date (YYYY-MM-DD, Optional)
Search all events after this date, formatted as YYYY-MM-DD.
max_date (YYYY-MM-DD, Optional)
Search all events before this date, formatted as YYYY-MM-DD.
tags (Optional)
A comma-separated list of tags. Events that have been tagged with any of the tags passed will be returned. 20 tags max.
per_page (Numeric, Optional, Default = 100)
Number of results to return per page. Max is 100 per page.
page (Numeric, Optional, Default = 1)
The page number of results to return.
sort (String, Optional, Default = start-date-asc)
The field and direction on which to sort the results. Distance sorts must ONLY be used if
location is specified.
Meaningful values:
- - distance-asc (Distance from provided location, ascending)
- - name-asc (Event name, descending alphabetically)
- - name-desc (Event name, ascending alphabetically)
- - start-date-asc (Event's start date, in chronological order)
- - start-date-desc (Event's start date, in reverse chronological order)
- - posted-date-asc (The date the event was added to Upcoming, in chronological order)
- - posted-date-desc (The date the event was added to Upcoming, in reverse chronological order)
backfill (String, Optional)
If the first page of results returned has fewer than
per_page results, try expanding the search.
Meaningful values:
- - later (Remove any limits on maximum starting date)
- - further (Double the existing search radius, up to 200 miles)
variety (Boolean, Optional)
Attempt to provide more varied results. Currently, this is implemented as not showing more than one event of each category. This will greatly reduce the amount of results returned. This feature is intended for situations where you want to show a great diversity of results in a small space.
Meaningful values:
- - 1 (that is, use parameter in URL as 'variety=1')
rollup (String, Optional)
Used to display all future events of an event. By default only the last event of an event is displayed. This option provides the mechanism to override that behavior.
Meaningful values:
- - none (Display all future events of an event)
token (Optional)
An authentication token. (
What's this?)
Response Notes
photo_url
For events with photos attached, we include a photo_url that refers to one of those photos. This is the priority order
for selecting which photo goes into the photo_url field:
- The photo marked as "official" by the person who added the event.
- The photo of a performer, if the person who added the event tagged it with a Y! Music performer.
- Any randomly selected photo uploaded directly to Upcoming.
- Any randomly selected photo from Flickr tagged to this event.
Official and Upcoming-hosted photos are 75x75px. Y! Music performer photos are 80x80px. Flickr photos vary but have a max height/width of 100px.
geographical fields
Within the response, several geographical fields refer to the geolocation of the underlying venue of the event.
These include latitude and longitude, as well as geocoding_precision, which specifies the precision to which the venue
address could be found and geocoded. The geocoding_ambiguous parameter serves as a warning that the geocoding is
likely to be erroneous.
Example Response
XML
<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" version="1.0">
<event id="12995" name="The Samples" description="" start_date="2005-04-16"
end_date="" start_time="19:00:00" end_time=""
personal="0" selfpromotion="0" metro_id="1" venue_id="155"
user_id="8172" category_id="1" date_posted="2005-02-14"
latitude="37.765" longitude="-122.396" geocoding_precision="address"
geocoding_ambiguous="0" venue_name="The Wiltern"
venue_address="3790 Wilshire Blvd" venue_city="Los Angeles"
venue_state_name="California" venue_state_code="ca"
venue_state_id="5" venue_country_name="United States"
venue_country_code="us" venue_country_id="1"
venue_zip="90010"
ticket_url="" ticket_price="" ticket_free="1" photo_url="" />
<event id="12996" name="The Samples" description="" start_date="2005-04-16"
end_date="" start_time="23:00:00" end_time=""
personal="0" selfpromotion="0" metro_id="1" venue_id="155"
user_id="8172" category_id="1" date_posted="2005-02-14"
latitude="37.7665" longitude="-122.43" geocoding_precision="address"
geocoding_ambiguous="0" venue_name="The Wiltern"
venue_address="3790 Wilshire Blvd" venue_city="Los Angeles"
venue_state_name="California" venue_state_code="ca"
venue_state_id="5" venue_country_name="United States"
venue_country_code="us" venue_country_id="1"
venue_zip="90010"
ticket_url="" ticket_price="" ticket_free="1" photo_url="" />
</rsp>
JSON
{ "rsp" : { "event" : [ { "category_id" : 2,
"date_posted" : "2009-01-28 08:42:24",
"description" : "",
"distance" : 43.100000000000001,
"distance_units" : "miles",
"end_date" : "",
"end_time" : -1,
"geocoding_ambiguous" : 0,
"geocoding_precision" : "address",
"id" : 1673283,
"latitude" : 37.762,
"longitude" : -122.435,
"metro_id" : "",
"name" : "Vagina Monologues",
"num_future_events" : 0,
"personal" : 0,
"photo_url" : "",
"selfpromotion" : 0,
"start_date" : "2009-04-16",
"start_date_last_rendition" : "Apr 16, 2009",
"start_time" : "19:30:00",
"ticket_free" : 0,
"ticket_price" : "",
"ticket_url" : "http://www.ticketsnow.com/InventoryBrowse/TicketList.aspx?PID=772555",
"url" : "http://www.ticketsnow.com/EventList/EventsList.aspx?EID=905",
"user_id" : 4,
"utc_end" : "2009-04-17 05:30:00 UTC",
"utc_start" : "2009-04-17 02:30:00 UTC",
"venue_address" : "429 Castro St",
"venue_city" : "San Francisco",
"venue_country_code" : "US",
"venue_country_id" : 1000000,
"venue_country_name" : "United States",
"venue_id" : 282390,
"venue_name" : "Castro Theater",
"venue_state_code" : "CA",
"venue_state_id" : 1000000,
"venue_state_name" : "CA",
"venue_zip" : 94114,
"watchlist_count" : 0
},
{ "category_id" : 1,
"date_posted" : "2009-01-28 09:29:00",
"description" : "Carola Zertuche presents music and dance with great performers of traditional flamenco.",
"distance" : 43.829999999999998,
"distance_units" : "miles",
"end_date" : "",
"end_time" : -1,
"geocoding_ambiguous" : 0,
"geocoding_precision" : "address",
"id" : 1691425,
"latitude" : 37.809600000000003,
"longitude" : -122.4106,
"metro_id" : "",
"name" : "Flamenco Thursdays",
"num_future_events" : 0,
"personal" : 0,
"photo_url" : "",
"selfpromotion" : 0,
"start_date" : "2009-04-16",
"start_date_last_rendition" : "Apr 16, 2009",
"start_time" : "20:00:00",
"ticket_free" : 0,
"ticket_price" : "$12",
"ticket_url" : "",
"url" : "",
"user_id" : 4,
"utc_end" : "2009-04-17 06:00:00 UTC",
"utc_start" : "2009-04-17 03:00:00 UTC",
"venue_address" : "1630 Powell St",
"venue_city" : "San Francisco",
"venue_country_code" : "us",
"venue_country_id" : 1000000,
"venue_country_name" : "United States",
"venue_id" : 83329,
"venue_name" : "Pena Pacha Mama",
"venue_state_code" : "CA",
"venue_state_id" : 1000000,
"venue_state_name" : "California",
"venue_zip" : 94133,
"watchlist_count" : 0
}
],
"stat" : "ok",
"version" : 1
}
}
Error Codes (sent in HTTP Response Header)
403 Not Authorized:
- Invalid authentication parameters - either that token was not found, or it may be deactivated. Please contact us for support.
404 Not Found:
- Missing valid api_key - Please create an API key using the above link.
- Your api_key is inactive or not found - Please contact us for support.
- Invalid country_id parameter
- Invalid state_id parameter
- Invalid metro_id parameter
- Invalid min_date parameter
- Invalid max_date parameter
- Invalid tags parameter
- Invalid per_page parameter
- Invalid page parameter
- Invalid sort parameter
- Cannot perform blank search without a metro_id
- event.search only supports up to 20 tags.
- event.search only supports up to 100 results per page.
- Invalid venue_id. Must be a single numeric value.
- Search location could not be geocoded or was formatted improperly. See the formatting examples at http://upcoming.yahoo.com/services/api/event.search.php.
- Search location was ambiguously geocoded. Please provide more detail in your search location.
- Invalid radius parameter. Must be a single numeric value equal to the miles of proximity to search within.
- Invalid radius parameter. Your radius exceeds the maximum allowed on a proximity search (100 miles).
- Invalid category_id. Must be a single or comma separated list of numeric values.
- Could not match this Place ID to a location
- Invalid backfill parameter (or backfill requested when page is greater than 1)
- Invalid variety parameter
- Could not convert Place ID to a latitude and longitude for backfill purposes
- Invalid woeid parameter