Welcome, Guest Sign In | Sign Up | Help
Upcoming API Documentation
Currently, the use of these APIs are restricted to non-commercial use only. If you'd like to use it for commercial purposes, please contact us first.
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.

woeid (Required)
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)


token (Optional)
An authentication token. (What's this?)

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 (i.e. non-US venues) will have blank values in the fields..

Example Response
<?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>		
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
Tools
Upcoming Badges for Your Blog/Website | Invite Friends | Groups | Developers API
Help
News Blog | Community Guidelines | FAQ | Contact Us | Suggestion Board