Method: /user_events

Retrieve a list of events on a user's calendar. By default, the next 10 events on a user calendar are returned. Use the limit parameter to change the number of events returned. Use the offset parameter to determine the offset from the from the beginning of the event list (just like the OFFSET clause in SQL). Use the sd or st parameter to specify a different start time. Use the ed or et parameter to specify a different end time.

Invocation

Request Parameters

Parameter Description Type Extra
key Zvents Developer API key String required
id ID (or login) of the user Integer or String required
limit The number of records to return (default: 10, maximum: 10). Zvents partners can exceed the maximum. Integer optional
offset The offset from the beginning of the event list (default: 0) Integer optional
sd Return only events that start on or after this date. (format: MM/DD/YYYY, defaults to today) String optional
ed Return only events that start on or before this date. This parameter can be used in conjunction with sd to return events within a specific date range. (format: MM/DD/YYYY) Integer optional
st Return only events that start at or after this time. (format: seconds since the epoch, e.g., 1142399089) String optional
et Return only events that start at or before this time. This parameter can be used in conjunction with st to return events within a specific time range. (format: seconds since the epoch, e.g., 1142399089) Integer optional

Example Request

Response Parameters

The response lists events on the user calendar.

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

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<rsp status="ok">
  <stream_count>1</stream_count>
  <event id="154927">
    <name>Sunday Jazz Series at the Improv:  The Jazz Cannon</name>
    <description>
      Since his arrival to the Bay Area to take the position of Coordinator
      of Jazz Studies at San Jose State University, Dr. Lington Has quickly
      become a mainstay of the local jazz scene. A recent graduate of North
      Texas State University, he has performed with several well-known artists:
      Maria Schneider and the Temptations to name a few, and arranged and
      composed for legendary trumpeter Maynard Ferguson and vocalist Jamie
      Davis. Dr. Lington also serves as Director of the San Jose Jazz Society
      Orchestra and Youth Jazz Orchestra. Listening samples online at
      www.aaronlington.com
      ---sanjosejazz.org
    </description>
    <summary></summary>
    <link>http://www.zvents.com/san-jose-ca/events/show/154927-sunday-jazz-series</link>
    <url>http://sanjosejazz.org/events.html</url>
    <external_urls>
      <external_url>
        <type>Web page</type>
        <anchor_text>Wikipedia page</anchor_text>
        <location>http://en.wikipedia.org/wiki/Jazz</location>
      </external_url>
    </external_urls>
    <performers>
      <performer>
        <id>1027111</id>
        <name>The Jazz Cannon</name>
        <link>http://www.zvents.com/performers/show/402217-the-jazz-cannon</link>
      </performer>
    </performers>
    <phone>(111) 222-3333</phone>
    <starttime>200603121500</starttime>
    <endtime>200603121700</endtime>
    <creator_id>3</creator_id>
    <price/>
    <venue_id>4553</venue_id>
    <parent_id>154927</parent_id>
    <tags>
      <tag>
        <name>live jazz</name>
      </tag>
    </tags>
    <categories>
      <category id="7">
        <id>7</name>
        <name>Music</name>
        <parent_id/>
        <depth>0</depth>
      </category>
    </categories>
    <images>
     <url>http://www.zvents.com/images/internal/img_885.jpg</url>
    </images>
  </event>
  <venue id="4553">
    <name>Improv Comedy Club</name>
    <description></description>
    <phone>(408) 280-7475</phone>
    <link>http://www.zvents.com/san-jose-ca/venues/show/4553-improv-comedy-club</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_types>
      <venue_type>
        <id>1</id>
        <name>Bar</name>
      </venue_type>
    </venue_types>
    <images>
     <url>http://www.zvents.com/images/internal/img_885.jpg</url>
    </images>
  </venue>
</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.

Possible Errors

This method may return one of the following errors.

Read the documentation on error formats.