Search Upcoming for public events by multiple facets. If optional authentication is provided, event.search also searches private events.
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.
ticket_sources (Optional)
A comma-separated list of ticket sources. Events having tickets from a specific ticket source (ticketmaster, robot, or user).
ticketmaster_artist_ids (optional)
A comma-separated list of ticketmaster artist unique ids. For http://www.ticketmaster.com/Janet-Jackson-tickets/artist/735353, this would be 735353.
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?)
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.
{ "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
}
}