Method: /search_within_group

Search for events within a group calendar by what, when and where parameters.

Invocation

Request Parameters

Parameter Description Type Extra
id The ID of the group to search. Integer required
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

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.

Read the documentation on error formats.