Zvents: API Documentation: Output Formats

Output Formats

Each API method can return output in one of several formats. This applies to both successful and unsuccessful method calls - meaning that both responses and error messages will be returned in the requested format. The following formats are supported:

XML Format (default)
RSS Format
JSON Format

All output messages are returned in XML format by default. To specify a different format, simply append the format parameter to the end of the request string.

Example XML Format (Default format)

e.g., http://www.zvents.com/rest/event/154925?key=YOUR_API_KEY

<?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>

Here is the DTD for the XML format. It is a document fragment, so opening it in your browser may not work. Instead, try saving it to disk and opening it with a text editor.

Example RSS Format

e.g., http://www.zvents.com/rest/event/154925?key=YOUR_API_KEY&format=rss

<rss xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xCal="urn:ietf:params:xml:ns:xcal">
  <channel>
    <title>REST API output from Zvents.com</title>
    <link>http://www.zvents.com/rest/event/154925?key=OJKHISXRWROUURTJERKLDHMQVPRIMKPYCXLOVNPCIBRMPLQIRAGMTFEMGAMSSKUM&format=rss</link>
    <ttl>60</ttl>
    <description>REST API output from Zvents.com</description>
    <stream_count>1</stream_count>
    <item>
      <title>Sunday Jazz Series at the Improv: Kristen Strom Quintet</title>
      <description>
        Bay Area Mainstay and Festival favorite Kristen Strom
        has performed with a number of jazz greats, including
        saxophonist-composer Jimmy Heath, trombonist Steve Turre,
        singer Kevin Mahogany and trumpeter Jon Faddis as well as in
        the San Jose Jazz Orchestra. At the Series, saxophonist Kristen
        Strom takes the stage with her quintet to perform standards and
        originals from her new release &quot;Intention&quot;
        (Open Path Studios). With a focus on the beauty of tone and
        melody, Strom leads a strong group of jazz notables: Scott Sorkin
        (guitar), John Shifflett (bass), Adam Sculman (keys) and Jason
        Lewis (drums). Listening samples online at www.kristenstrom.com
        ---sanjosejazz.org
      </description>
      <guid>http://www.zvents.com/san-jose-ca/events/show/154925</guid>
      <link>http://www.zvents.com/san-jose-ca/events/show/154925</link>
      <dc:creator>3</dc:creator>
      <geo:lat>37.3362</geo:lat>
      <geo:long>-121.889</geo:long>
      <pubDate>Thu, 15 Dec 2005 03:30:13 -0800</pubDate>
      <dc:date>2005-12-15T03:30:13-0800</dc:date>
      <xCal:dtstart>2006-02-26 15:00:00 -0800</xCal:dtstart>
      <xCal:dtend>2006-02-26 17:00:00 -0800</xCal:dtend>
      <xCal:location>http://www.zvents.com/san-jose-ca/venues/show/4553</xCal:location>
      <xCal:x-calconnect-venue>
        <xCal:x-calconnect-venue-id>4553</xCal:x-calconnect-venue-id>
        <xCal:adr>
          <xCal:x-calconnect-venue-name>Improv Comedy Club and Restaurant</xCal:x-calconnect-venue-name>
          <xCal:x-calconnect-street>62 S. 2nd St.</xCal:x-calconnect-street>
          <xCal:x-calconnect-city>San Jose</xCal:x-calconnect-city>
          <xCal:x-calconnect-region>California</xCal:x-calconnect-region>
          <xCal:x-calconnect-postalcode>95113</xCal:x-calconnect-postalcode>
          <xCal:x-calconnect-country>United States</xCal:x-calconnect-country>
        </xCal:adr>
        <xCal:url>http://improv2.com/v3/index.php?option=content&task=blogcategory&id=40&Itemid=50</xCal:url>
        <xCal:x-calconnect-tel>(408) 280-7475</xCal:x-calconnect-tel>
      </xCal:x-calconnect-venue>
    </item>
  </channel>
</rss>

Example JSON Format

e.g., http://www.zvents.com/rest/event/154925?key=YOUR_API_KEY&format=json

{"rsp":{"status":"ok",content:{"events":[{"endTime":"Sun Feb 26 17:00:00 GMT 2006","id":154925,"name":"Sunday Jazz Series at the Improv: Kristen Strom Quintet","phone":"(408) 288-7557","price":"","repeatPattern":"","repeatType":0,"repeatUntil":"Tue Mar 14 00:00:00 GMT 2006","startTime":"Sun Feb 26 15:00:00 GMT 2006","url":"http://sanjosejazz.org/events.html","vid":4553,"images":[]}],"event_count":1,"venues":[{"address":"62 S. 2nd St.","id":4553,"name":"Improv Comedy Club and Restaurant","phone":"(408) 280-7475","city":"San Jose","country":"United States","latitude":37.3362,"longitude":-121.889,"state":"California","timezone":"US/Pacific","url":"http://improv2.com/v3/index.php?option=content&task=blogcategory&id=40&Itemid=50","images":[]}],"venue_count":1}}}

Note: The startTime and endTime fields always come back with timezone set to GMT. This timezone should be ignored in the response. The time returned is always in the timezone of the venue at which the event occurs.

JSON Callbacks
Use the callback URL parameter to include a callback wrapper in the JSON output.
e.g., http://www.zvents.com/rest/event/154925?key=YOUR_API_KEY&format=json&callback=callback

callback({"rsp":{"status":"ok","content":{"events":[{"endTime":"Sun Feb 26 17:00:00 GMT 2006","id":154925,"name":"Sunday Jazz Series at the Improv: Kristen Strom Quintet","phone":"(408) 288-7557","price":"","startTime":"Sun Feb 26 15:00:00 GMT 2006","url":"http://sanjosejazz.org/events.html","vid":4553,"images":[]}],"event_count":1,"venues":[{"address":"62 S. 2nd St.","id":4553,"name":"Improv Comedy Club and Restaurant","phone":"(408) 280-7475","city":"San Jose","country":"United States","latitude":37.3362,"longitude":-121.889,"state":"California","timezone":"US/Pacific","url":"http://improv2.com/v3/index.php?option=content&task=blogcategory&id=40&Itemid=50","images":[]}],"venue_count":1}}});