API Method /events/search
This function handles event search. It performs the requested search,
returning the results as an XML file. See the search box at http://eventful.com/events for an example interface.
- This method controls access via authentication. Oauth is NOT needed but an application key (app_key query string parameter) is required.
- keywords string
- The search keywords. (optional)
- location string
- A location name to use in filtering the search results. Locations in the form "San Diego", "San Diego, TX", "London, United Kingdom", and "Calgary, Alberta, Canada" are accepted, as are postal codes ("92122") and venue IDs ("V0-001-000268633-5"). Common geocoordinate formats ("32.746682, -117.162741") are also accepted, but the "within" parameter is required in order to set a search radius. (optional)
- date string
- Limit this list of results to a date range, specified by label or exact range. Currently supported labels include: "All", "Future", "Past", "Today", "Last Week", "This Week", "Next week", and months by name, e.g. "October". Exact ranges can be specified the form 'YYYYMMDD00-YYYYMMDD00', for example '2012042500-2012042700'; the last two digits of each date in this format are ignored. (optional)
- category string
- Limit the search results to this category ID. A list of categories may be specified separated by commas. See /categories/list for a list of categories and their IDs. (optional)
- ex_category string
- Exclude search results from including this category ID. A list of categories may be specified separated by commas. See /categories/list for a list of categories and their IDs. (optional)
- within integer
- If within is set and the "location" parameter resolves to a specific geolocation, the search will be restricted to the specified radius. If the "location" parameter does not resolve to a specific location, this parameter is ignored. (optional)
- units string
- One of "mi" or "km", the units of the "within" parameter. Defaults to "mi".(optional)
- count_only boolean
- If count_only is set, an abbreviated version of the output will be
returned. Only total_items and search_time elements are included in the result. (optional)
- sort_order string
- One of 'popularity', 'date', or 'relevance'. Default is 'relevance'.
- sort_direction string
- One of 'ascending' or 'descending'. Default varies by sort_order.
- page_size integer
- The desired number of results per page. (optional)
- page_number integer
- The desired page number. (optional)
- image_sizes string
- A comma separted list of image_sizes desired. See Faq for list of possible image sizes.
- languages integer
- Return our guess of each event language. ("Undetermined" is a possibility) (optional)
- mature string
- Sets the level of filtering for events marked as "mature" due to keywords in the title or description. One of 'all' (no filtering), 'normal', or 'safe'. 'Normal' mature filtering consists of words that are clearly profanities and inappropriate for younger audiences. 'Safe' mature filtering consists of all normal mature filtered words, as well as other terms that may be used as inappropriate innuendo. A 'safe' filter may eliminate events that are benign in nature, but contain questionable content based on keywords. Defaults to 'all'. (optional)
- include string
- Indicates that optional sections should be included in the result XML. Multiple section names can be indicated, separated by commas (e.g. 'categories,links').
Sections include 'categories', 'subcategories', 'popularity', 'tickets', 'price', and 'links'. (optional)
- change_multi_day_start boolean
- If set changes the start_date of long duration events (lasting multiple days) to the beginning of the search date range. It will also give the next occurence of a recurring event after the start range. This will prevent an event from appearing to be outside the date range requested . (optional)
Example Request 1 - Any event in San Diego with the title books in it.
Example Request 2 - Any event withing 25 miles of a specific Lat / Long value in San Diego
Output from this function is an XML block with the following constructs:
- total_items integer
- The total number of events matching this search. This can be an
approximation if we wish.
- page_size integer
- The number of events per "page" returned.
- page_count integer
- The number of "pages" of output.
- page_number integer
- The current "page" number.
- page_items integer
- The number of events returned in this block. This is not necessarly the
same as page_size. The last page, for instance, will probably not be a full
- first_item integer
- The item number of the first element on this page.
- last_item integer
- The item number of the last element on this page.
- search_time float
- The fractional number of seconds it took to satisfy this query.
- events array
- An array of page_items events. Each event entry has the following structure:
- id string
- The unique ID for this event. Presented as an event
object attribute. See the example below.
- url string
- The page URL for this event on eventful.com.
- title string
- The event title.
- description string
- The event description.
- start_time string
- The event start time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").
- stop_time string
- The event stop time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").
- venue_id integer
- The venue ID.
- venue_url string
- The page URL for this venue on eventful.com.
- venue_name string
- The venue name.
- venue_display boolean
- Whether or not the venue name should be displayed in certain cirumstances.
Eventful's notion of a venue is a bit broader than you might think. For example,
events for which only the postal code is known have a venue named "Postal code
46311, US", for instance. In these cases, a traditional address block looks a
bit unusual, and Eventful chooses not to display the venue name in these cases.
You may wish to do the same, and the venue_display parameter allows you to do that.
- venue_address string
- The venue address.
- city_name string
- The venue city_name.
- region_name string
- The venue state/province/other name.
- region_abbr string
- The venue state/province/other abbreviation.
- postal_code string
- The venue postal code.
- country_name string
- The venue country name.
- all_day integer
- A false value (0) indicates that the start_time and stop_time are as listed. If the all_day flag is set to 1 (all day) or 2 (no time specified), then the time should be omitted from start_time and stop_time.
- latitude signed float
- The venue latitude.
- longitude signed float
- The venue longitude.
- geocode_type string
- The method used to geocode the venue latitude and longitude.
- trackback_count integer
- The number of trackback entries associated with this event.
- calendar_count integer
- The number of calendars to which this event has been added.
- comment_count integer
- The number of comments associated with this event.
- link_count integer
- The number of URLs associated with this event.
- created string
- The event creation time (e.g. "2005-03-01 19:00:00").
- owner string
- The username of the event owner.
- modified string
- The event modification time (e.g. "2006-01-03 21:35:09").
Example XML Response
<?xml version="1.0" encoding="UTF-8"?>
<venue_name>San Diego Sports Arena</venue_name>
<venue_address>3500 Sports Arena Boulevard</venue_address>
This method may return these errors in an error document:
- Authentication error
- The specified user was not found or provided invalid credentials.
- Missing parameter
- Either the 'keywords', 'location', or 'date' parameter is required.