API Method /venues/search

This function handles venue search. It performs the requested search, returning the results as an XML file.

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.(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)
page_size integer
The desired number of results per "page".(optional)
page_number integer
The desired "page" number.(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)
sort_order string
One of 'popularity', 'relevance', or 'venue_name'. Default is 'relevance'. (optional)
sort_direction string
One of 'ascending' or 'descending'. Default varies by sort_order. (optional)

Example Request

Here's an example venue search URL:

http://api.eventful.com/rest/venues/search?...&keywords=Restaurant&location=San+Diego

Output Parameters

Output from this function is an XML block with the following constructs:
total_items integer
The total number of venues matching this search.
page_size integer
The number of venues per "page" of returned.
page_count integer
The number of "pages" of output.
page_number integer
The current "page" number.
page_items integer
The number of venues returned in this block. This is not necessarly the same as page_count. 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.
venues array
An array of count venues. Each venue is a separate <venue> construct with the following structure:
id string
The unique ID for this venue. Presented as a venue object attribute. See the example below.
url string
The page URL for this venue on eventful.com.
venue_name string
The venue name.
description string
The venue description.
city_name string
The venue city.
region_name string
The venue state/province/other.
postal_code string
The venue country.
country_name string
The venue country.
latitude signed float
The venue latitude in degrees.
longitude signed float
The venue longitude in degrees.
geocode_type string
The method used to geocode the venue latitude and longitude.
event_count integer
The number of upcoming events at this venue.

Example XML Response

<?xml version="1.0" encoding="UTF-8"?>
<search version="0.2">
  <total_items>4</total_items>
  <page_size>10</page_size>
  <page_count>1</page_count>
  <page_number>1</page_number>
  <page_items>4</page_items>
  <first_item>1</first_item>
  <last_item>4</last_item>
  <search_time>0.004</search_time>
  <venues>
    <venue id="V0-001-000102741-0">
      <url>http://eventful.com/venues/san-diego/humphreys-concerts-by-the-bay-/
      V0-001-000102741-0?utm_source=apis&utm_medium=apim&utm_campaign=apic
      </url>
      <venue_name>Humphrey's Concerts By the Bay</venue_name>
      <description></description>
      <venue_type></venue_type>
      <address>2241 Shelter Island Drive</address>
      <city_name>San Diego</city_name>
      <region_name>California</region_name>
      <postal_code>92106</postal_code>
      <country_name>United States</country_name>
      <longitude>-117.222</longitude>
      <latitude>32.7173</latitude>
      <event_count>30</event_count>
    </venue>
    <venue id="V0-001-000105166-6">
    ...
    </venue>
    <venue id="V0-001-000102583-8">
    ...
    </venue>
    <venue id="V0-001-000102854-3">
    ...
    </venue>
  </venues>
</search>