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.

Arguments

authentication
This method controls access via optional user authentication.
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"). Full addresses ("1 Infinite Loop, Cupertino, CA") and common geocoordinate formats ("32.746682, -117.162741") are also accepted, but the "within" parameter is recommended 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 take the form 'YYYYMMDDHH-YYYYMMDDHH', e.g. '2008042500-2008042723'. (optional)
category string
Limit the search results to this category ID. 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', 'title', 'relevance', or 'venue_name'. Default is 'date'. (optional)
sort_direction string
One of 'ascending' or 'descending'. Default varies by sort_order. (optional)
page_size integer
The desired number of results per page. (optional)
page_number integer
The desired page number. (optional)

Example Request

http://api.eventful.com/rest/events/search?...&keywords=books&location=San+Diego&date=Future

Output Parameters

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 page.
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 boolean
If true, this event lasts all day.
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"?>

<search>
  <total_items>1471</total_items>
  <page_size>20</page_size>
  <page_count>74</page_count>
  <page_number>1</page_number>
  <page_items>20</page_items>
  <first_item>1</first_item>
  <last_item>20</last_item>
  <search_time>0.022</search_time>
  <events>
    <event id="E0-001-009415668-0">
      <title>Kanye West</title>
      <url>http://eventful.com/events/san-diego/music-kanye-west-tickets-/E0-001-009415668-0?utm_source=apis&amp;utm_medium=apim&amp;utm_campaign=apic</url>
      <description></description>
      <start_time>2008-04-20 19:00:00</start_time>
      <stop_time></stop_time>
      <tz_id></tz_id>
      <tz_olson_path></tz_olson_path>
      <tz_country></tz_country>
      <tz_city></tz_city>
      <venue_id>V0-001-000312317-0</venue_id>
      <venue_url>http://eventful.com/venues/san-diego/san-diego-sports-arena-/V0-001-000312317-0?utm_source=apis&amp;utm_medium=apim&amp;utm_campaign=apic</venue_url>
      <venue_name>San Diego Sports Arena</venue_name>
      <venue_display>1</venue_display>
      <venue_address>3500 Sports Arena Boulevard</venue_address>
      <city_name>San Diego</city_name>
      <region_name>California</region_name>
      <region_abbr>CA</region_abbr>
      <postal_code>92110</postal_code>
      <country_name>United States</country_name>
      <country_abbr2>US</country_abbr2>
      <country_abbr>USA</country_abbr>
      <latitude>32.753651</latitude>
      <longitude>-117.21163</longitude>
      <geocode_type>EVDB Geocoder</geocode_type>
      <all_day>0</all_day>
      <recur_string></recur_string>
      <trackback_count>0</trackback_count>
      <calendar_count>3</calendar_count>
      <comment_count>0</comment_count>
      <link_count>6</link_count>
      <going_count>0</going_count>
      <watching_count>4</watching_count>
      <created>2008-02-26 23:02:38</created>
      <owner>evdb</owner>
      <modified>2008-03-26 16:53:27</modified>
      <performers>
        <performer>
          <id>P0-001-000001486-2</id>
          <url>http://eventful.com/performers/kanye-west/rapper-/P0-001-000001486-2?utm_source=apis&amp;utm_medium=apim&amp;utm_campaign=apic</url>
          <name>Kanye West</name>
          <short_bio>Rapper</short_bio>
          <creator>bsk20021</creator>
          <linker>evdb</linker>
        </performer>
      </performers>
      <image>
        <url>http://images.evdb.com/images/small/I0-001/000/613/154-1.png</url>
        <width>48</width>
        <height>48</height>
        <caption></caption>
        <thumb>
          <url>http://images.evdb.com/images/thumb/I0-001/000/613/154-1.png</url>
          <width>48</width>
          <height>48</height>
        </thumb>
        <small>
          <url>http://images.evdb.com/images/small/I0-001/000/613/154-1.png</url>
          <width>48</width>
          <height>48</height>
        </small>
        <medium>
          <url>http://images.evdb.com/images/medium/I0-001/000/613/154-1.png</url>
          <width>128</width>
          <height>128</height>
        </medium>
      </image>
      <privacy>1</privacy>
      <calendars>
        <calendar>
          <id>C0-001-000080462-7</id>
          <name>Featured Events</name>
        </calendar>
        <calendar>
          <id>C0-001-000080463-6</id>
          <name>Hot Events</name>
        </calendar>
        <calendar>
          <id>C0-001-000097014-2</id>
          <name>Shows</name>
        </calendar>
      </calendars>
      <groups></groups>
      <going></going>
      ...
  </events>
</search>

Error Codes

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.