Zvents: API Documentation: /search

Method: /search

Search for events by what, when and where parameters.

Invocation

This method can be invoked using either HTTP GET or HTTP POST.
This method requires an API key
This method can also be invoked using the alias search_for_events

Request Parameters

Parameter	Description	Type	Extra
what	The string against which events are matched. (e.g., parade)	String	optional
when	A string specifying a date range for the search (e.g., today, this week, next week, friday, etc.). Explicit date ranges can be specified by separating two dates with the word "to" (e.g., monday to thursday, 10/30/2007 to 11/4/2007). Leave this string blank to search all future events.	String	optional
where	A string describing a location around which the search results will be restricted. (e.g., san francisco, ca or 94131). You can also specify a location using a longitude/latitude coordinate pair using the notation -74.0:BY:40.9 If this field is left blank, the location is automatically determined by mapping the client IP address to latitude/longitude coordinates. Since IP-mapping is not guaranteed to be accurate, it is a good idea to always specify a location.	String	optional
radius	The number of miles around the location (specified in the where field) to search. If this field is left blank, a default radius is supplied. The default radius varies according to the location specified in the where field.	Float	optional
limit	The maximum number of matching events to return. The default is 10 and maximum is 10. Zvents partners can exceed the maximum.	Integer	optional
offset	The number of events to skip from the beginning of the search results. If a search matches 1000 events, returning 25 events starting at offset 100 will return event numbers 100-125 that match the search..	Integer	optional
trim	Set to 1 if repeating events should be trimmed from the search results. Set to 0 to return repeating events. If the trim option is enabled, only 1 event will be returned from each repeating series that matches the search. The number of events within the series that match the search is returned in the series_count response parameter. Defaults to 1.	Integer	optional
sort	Set to 1 to sort search results by start time. Set to 0 to sort search results by relevance. Defaults to 0.	Integer	optional
cat	Restrict your search to items that belong to a specific category. You must provide a category identifier which can be determined using the categories API call.	Integer	optional
catex	Exclude items from a specific category from the search. You must provide a category identifier which can be determined using the categories API call.	Integer	optional

Example Request

http://www.zvents.com/rest/search?what=dancing&where=san%20francisco,%20ca&when=this%20month&limit=10&key=YOUR_API_KEY

Response Parameters

The response lists events matching the search terms.

Parameter	Description	Type	Mandatory
id	The unique ID for the event.	Integer	Y
name	The name of the event.	String	Y
summary	A summary of the event.	String
description	A full description of the event.	String
link	The URL for this event on www.zvents.com.	String	Y
url	The external web page for the event.	String
external urls	A list of additional external urls associated with this event (e.g., a link to a performer's web page).	String List
phone	The phone number for the event.	String
starttime	The starttime of the event. (format YYYYMMDDHHMM)	Integer	Y
endtime	The endtime of the event. (format YYYYMMDDHHMM)	Integer
creator_id	The ID of the user that created the event.	Integer	Y
price	The price of the event (if available).	String
age suitability	Age suitability for this event if one was supplied by the event creator. Possible values are All Ages, Kids and up, Teens and up, 18 and up, 21 and up, Senior Citizens, None Specified.	String
venue_id	The ID of the venue at which the event occurs.	Integer	Y
parent_id	If this event is part of a repeating series, this field provides the ID of the event that is the parent of the repeating series. Note that the ID may point to the current event.	Integer
images	If this event has images, this field provides a list of URLs for those images.	String List
tags	A list of tags associated with this event.	String List
performers	A list of performers appearing at this event.	String List
categories	A list of categories associated with this event.	String List
series_count	The number of events in the repeating series that match this search. This value is non-zero only if the event belongs to a repeat series (and multiple events within that series match the search) and the trim option (see above) has been enabled.	Integer
search_info	A list of parameters describing the search that was just performed. This information is valuable for examining the default parameters of a search, some of which are fixed and some are contextual. The following values are supplied: what: The string against which items were matched. This is the same value passed into the input parameter of the same name. when: The time constraint for this search. This is the same value passed into the input parameter of the same name. Only applies to even searches. where: The geographic constraint for this search. This is the same value passed into the input parameter of the same name. radius: The radius of the search. st: The type of search performed: event or venue. sst: The start time of the search expressed in seconds since 1970/01/01 00:00:00 set: The end time of the search expressed in seconds since 1970/01/01 00:00:00 srss: The number of items returned in this search. This is the same value passed into the input parameter of the same name provided that the input parameter did not exceed the maximum value.	Hash

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
  <stream_count>1081</stream_count>
  <event id="136053">
    <name>Ballroom Dancing</name>
    <description>6 times on Wednesdays
      $75.00 Member
      $85.00 Public
      Introduces the fundamentals of ballroom dance, basic steps and
      patterns. Included will be waltz, rumba and Night Club Two-Step.
      --- http://maven.jccsf.org/
    </description>
    <url>http://maven.jccsf.org/content_main.aspx?catid=376</url>
    <starttime>200603011830</starttime>
    <endtime>200603011930</endtime>
    <creator_id>28</creator_id>
    <price></price>
    <venue_id>8102</venue_id>
    <parent_id>136053</parent_id>
    <series_count>3</series_count>
  </event>
  <event id="139885">
    <name>Teen Dance</name>
    <description>22 times on Thursdays
      Age Requirement:  Ages 12-17
      Join us for this unique class designed with you in mind. This
      twice-per-week class lets you focus on several dance techniques each
      week. On Tuesdays we will concentrate on ballet. Warm ups, new
      techniques, barre work and floor work make this class a positive
      learning experience.

      Thursdays we will explore different dance forms. From hip-hop and
      jazz to tap, students will learn new techqnieus and fun dance routines.

      All levels of experience welcome.
      --- http://maven.jccsf.org/
    </description>
    <url>http://maven.jccsf.org/content_main.aspx?catid=248</url>
    <starttime>200603020500</starttime>
    <endtime>200603020600</endtime>
    <creator_id>28</creator_id>
    <price>$410.00 Member, $430.00 Public</price>
    <venue_id>8102</venue_id>
    <parent_id>0</parent_id>
    <series_count/>2</series_count>
  </event>
  <venue id="8012">
    <name>Improv Comedy Club and Restaurant</name>
    <description></description>
    <phone>(408) 280-7475</phone>
    <link>http://www.zvents.com/san-jose-ca/venues/show/4553-improve-comedy-club-and-restaurant</link>
    <url>http://improv2.com/v3/index.php?option=content&task=blogcategory&id=40&Itemid=50</url>
    <creator_id>2</creator_id>
    <address>62 S. 2nd St.</address>
    <city>San Jose</city>
    <zipcode>95113</zipcode>
    <state>California</state>
    <country>United States</country>
    <timezone>US/Pacific</timezone>
    <latitude>37.3362</latitude>
    <longitude>-121.889</longitude>
  </venue>
  <search_info>
    <sst>1149145200</sst>
    <set>1151737199</set>
    <srss>10</srss>
    <what>dancing</what>
    <when>this month</when>
    <where>san francisco, ca</where>
    <radius>5.0</radius>
    <st>event</st>
  </search_info>
</rsp>

Output Fields

Note: The REST API does not return all possible fields for each item by default. Since some response fields are not used by most API users, these fields are suppressed from the response by default in order to reduce latency for the common calls. Additional fields can be enabled in the response using the fields parameters documented in the 'Optimizing API calls for performance' section.

Output Formats

REST responses can be returned in a number of different formats include XML, JSON and CSV. Read the documentation on output formats.

Performance Considerations

For performance reasons, newly created items (events, venues, etc.) will not appear in search results from the REST API for up to an hour after the item was created. It is possible to eliminate this delay when using a commercial API key. Contact support for details.

Possible Errors

This method may return one of the following errors.

Unrecognized Date Format: The date string provided in when was not recognized.
Unrecognized Location: The location string provide in where was not recognized.
Invalid API Key: The API key supplied is not valid.
Call Limit Exceeded: The API key has exceeded the daily maximum number of calls.

Output Fields

Output Formats

REST responses can be returned in a number of different formats include XML, JSON and CSV. Read the documentation on output formats.