event.getBestInPlace [HTTP GET]
Search Upcoming for featured or popular events in a specified place
Arguments
api_key (Required)
Your API application key. If you don't have one,
create one.
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.
woeid (Optional)
The WOEID of the place to which search results will be restricted.
per_page (Numeric, Optional, Default = 10)
Number of results to return per page. Max is 10 per page.
sort (String, Optional)
The field and direction on which to sort the results.
Meaningful values:
- - score-asc (Relevance ascending)
- - score-desc (Relevance descending)
filter (String, Optional, Default = popular)
Use this to filter the search results to get the best type of events in the given place.
Meaningful values:
- - popular (Retrieve the events in my area that others in my area find interesting)
- - featured (Retrieve the events in my area that look interesting)
Response Notes
Within the response, several geographical parameters have been added that 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, and also the geocoding_ambiguous parameter, which serves as a warning that the geocoding is likely to be erroneous.
Any event at a venue that could not be geocoded at all will have blank values in the fields.
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="0" 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" : 1,
"date_posted" : "2008-12-02 13:00:39",
"description" : "",
"distance" : 1.4399999999999999,
"distance_units" : "miles",
"end_date" : "",
"end_time" : -1,
"geocoding_ambiguous" : 0,
"geocoding_precision" : "address",
"id" : 1405524,
"latitude" : 34.043500000000002,
"longitude" : -118.26600000000001,
"metro_id" : 1,
"name" : "Britney Spears, Pussycat Dolls",
"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" : "",
"ticket_url" : "",
"url" : "",
"user_id" : 11200,
"utc_end" : "2009-04-17 06:00:00 UTC",
"utc_start" : "2009-04-17 03:00:00 UTC",
"venue_address" : "1111 S Figueroa St",
"venue_city" : "Los Angeles",
"venue_country_code" : "us",
"venue_country_id" : 1,
"venue_country_name" : "United States",
"venue_id" : 35657,
"venue_name" : "Staples Center",
"venue_state_code" : "ca",
"venue_state_id" : 5,
"venue_state_name" : "California",
"venue_zip" : 90015,
"watchlist_count" : 6
},
{ "category_id" : 1,
"date_posted" : "2008-12-07 03:52:24",
"description" : "",
"distance" : 1.4399999999999999,
"distance_units" : "miles",
"end_date" : "",
"end_time" : -1,
"geocoding_ambiguous" : 0,
"geocoding_precision" : "address",
"id" : 1422344,
"latitude" : 34.043500000000002,
"longitude" : -118.26600000000001,
"metro_id" : 1,
"name" : "Britney Spears",
"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" : "",
"ticket_url" : "http://tickets.yahoo.com/search.html?performanceid=6953803&pid=1",
"url" : "",
"user_id" : 4,
"utc_end" : "2009-04-17 06:00:00 UTC",
"utc_start" : "2009-04-17 03:00:00 UTC",
"venue_address" : "1111 S Figueroa St",
"venue_city" : "Los Angeles",
"venue_country_code" : "us",
"venue_country_id" : 1,
"venue_country_name" : "United States",
"venue_id" : 35657,
"venue_name" : "Staples Center",
"venue_state_code" : "ca",
"venue_state_id" : 5,
"venue_state_name" : "California",
"venue_zip" : 90015,
"watchlist_count" : 4
}
],
"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.
- Woeid is a required parameter
- Invalid woeid parameter
- Invalid sort parameter
- Invalid filter parameter
- Invalid per_page parameter
- event.getBestInPlace only supports up to 10 results per page