XML Event Feeds

If your application requires importing a large set of events into your own data store, Eventful can generate XML files suitable for import. XML feed files are delivered on a weekly basis, with update files available daily.Since the list of events can be rather large we recommend that your xml importer be based on a SAX implementation of an XML paraser or else your application may run out of memory. For more information about SAX see the Sax wiki article.

For more information about event XML feeds, email us at develop@eventful.com.

Feed File Structure

Feed files usually contain three major sections: a list of events, a list of related venues, and a list of related performers.

Each venue and performer is linked by ID to one or more records in the events section. For example, a Vampire Weekend concert at The Casbah will have an event record with the ID of the Casbah venue (in a venue_id field) and the ID of the Vampire Weekend performer (in an id field under the performers block).

In some cases, a subset of the performer and/or venue details may be embedded in the event record. The embedded fields have the same definitions as they would separately.

Not all feeds contain the same fields; each is customized for the needs of the client. Some may include fields not listed here, and others may exclude some of these fields.

Events

<event>
  <id>E0-001-016881998-1@2008120711</id>
  <url>http://eventful.com/paloalto/events/living-legocy-legendary-/E0-001-016881998-1@2008120711</url>
  <title>Living LEGO-cy - Legendary LEGOs and Terrific Trains</title>
  <description> The Museum of American Heritage (MOAH), The Bay Area LEGO&amp;reg; User Group (BayLUG) and Bay Area LEGO Train Club (BayLTC) are again combining forces this winter to repeat last year's spectacular Holiday season display at MOAH. MOAH visitors can explore a variety of LEGO creations and an operating LEGO train layout featuring a wide variety of creations by club members. Highlighting it all is &lt;i&gt;Holidays in the Bay Area&lt;/i&gt;, a 12 by 25 foot train layout incorporating multiple trains running through city, farm, and suburban scenes. How many Bay Area locales and structures will you be able to indentify? Come and find out just how many clever ways LEGO can be used. Club members will be present during weekend hours to answer questions and support the displays.</description>
  <start_time>2008-12-07 11:00:00</start_time>
  <stop_time></stop_time>
  <tz_id></tz_id>
  <tz_olson_path></tz_olson_path>
  <tz_country></tz_country>
  <tz_city></tz_city>
  <venue_id>V0-001-000170898-6</venue_id>
  <all_day>0</all_day>
  <recur_string>on various dates</recur_string>
  <recurrence>
    <description>on various dates</description>
    <instances>
      <instance>
        <id>E0-001-016881998-1@2009053008</id>
        <start_time>2009-05-30 11:00:00</start_time>
        <stop_time></stop_time>
        <all_day>0</all_day>
      </instance>
      <instance>
        <id>E0-001-016881998-1@2009053108</id>
        <start_time>2009-05-31 11:00:00</start_time>
        <stop_time></stop_time>
        <all_day>0</all_day>
      </instance>
      <instance>
        <id>E0-001-016881998-1@2009060108</id>
        <start_time>2009-06-01 11:00:00</start_time>
        <stop_time></stop_time>
        <all_day>0</all_day>
      </instance>
      <instance>
        <id>E0-001-016881998-1@2009060208</id>
        <start_time>2009-06-02 11:00:00</start_time>
        <stop_time></stop_time>
        <all_day>0</all_day>
      </instance>
    </instances>
  </recurrence>
  <created>2008-10-24 03:17:59</created>
  <owner>evdb</owner>
  <privacy>1</privacy>
  <free></free>
  <price></price>
  <modified>2008-11-03 04:26:34</modified>
  <performers></performers>
  <image>
    <url>http://static.eventful.com/images/small/I0-001/001/321/255-2.gif</url>
    <width>48</width>
    <height>48</height>
    <thumb>
      <url>http://static.eventful.com/images/thumb/I0-001/001/321/255-2.gif</url>
      <width>48</width>
      <height>48</height>
    </thumb>
    <small>
      <url>http://static.eventful.com/images/small/I0-001/001/321/255-2.gif</url>
      <width>48</width>
      <height>48</height>
    </small>
    <medium>
      <url>http://static.eventful.com/images/medium/I0-001/001/321/255-2.gif</url>
      <width>128</width>
      <height>128</height>
    </medium>
  </image>
  <categories>
    <category>
      <id>art</id>
      <name>Art, Antiques, Crafts</name>
    </category>
    <category>
      <id>attractions</id>
      <name>Museums, Zoos, Attractions</name>
    </category>
  </categories>
  <tags>
    <tag id="blues">
      <title>Blues</title>
      <owner>evdb</owner>
    </tag>
    <tag id="concert">
      <title>concert</title>
      <owner>chris_radcliff</owner>
    </tag>
    <tag id="concerts">
      <title>concerts</title>
      <owner>insightmg9</owner>
    </tag>
    <tag id="experimental">
      <title>experimental</title>
      <owner>insightmg9</owner>
    </tag>
    <tag id="jazz">
      <title>jazz</title>
      <owner>insightmg9</owner>
    </tag>
    <tag id="music">
      <title>music</title>
      <owner>insightmg9</owner>
    </tag>
  </tags>
  <links>
    <link id="36634942">
      <url>http://gigaticket.com/ResultsTicket.aspx?evtid=1005735&amp;ppcsrc=onsite</url>
      <type>Info</type>
      <description>Buy tickets from gigaticket.com!</description>
      <username>evdb</username>
      <time>2009-01-31 22:22:57.923265</time>
    </link>
    <link id="36819886">
      <url>http://www.stubhub.com/tickets/opeth-boston-house-of-blues-boston-5-2-2009-791626/?ticket_finder=1074&amp;sub=Buy_Tickets</url>
      <type>Tickets</type>
      <description>Buy tickets at StubHub.com</description>
      <username>evdb</username>
      <time>2009-02-02 23:02:58.455366</time>
    </link>
  </links>
</event>

Key Event Fields

id string
The unique ID for this event.
url string
The page URL for this event on eventful.com.
title string
The event title.
description string
The event description.
start_time string
The event start time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").
stop_time string
The event stop time, if any, in ISO 8601 format (e.g. "2005-03-01 19:00:00").
tz_id integer
Eventful's internal timezone identifier. Not terribly useful unless you wish to give this back to Eventful at some time in the future.
tz_olson_path string
The event timezone, as listed in the Olson timezones database (e.g. "America/New_York").
tz_country string
tz_city string
tz_city and tz_country together represent the city/country pair timezone choice made by the user.
all_day integer
A false value (0) indicates that the start_time and stop_time are as listed. If the all_day flag is set to 1 (all day) or 2 (no time specified), then the time should be omitted from start_time and stop_time.
venue_id string
The venue ID. For all venue information, including geolocation and venue time zone, refer to the record in the venues section.
recur_string string
If this event recurs, a human-readable description of the recurrence, e.g. "repeats daily until August 1, 2009." For optional display alongside the start_time.
recurrence
(alternate) If this event recurs, a block of recurrence information for this and related events.
description string
a human-readable description of the recurrence, e.g. "repeats daily until August 1, 2009." For optional display alongside the start_time.
instances string
A list of individual dates for this event.
id string
The event ID for this particular instance of the event.
start_time string
The instance start time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").
stop_time string
The instance stop time, if any, in ISO 8601 format (e.g. "2005-03-01 19:00:00").
all_day boolean
True (1) if the instance is an all day event, false (0) otherwise.
created string
The date & time the event was initially created.
owner string
The username of the event owner.
privacy integer
Access level for this event. 1 is public, 2 is private, 3 is private but shareable.
free boolean
1 if the event is free, 0 otherwise, blank if unknown.
price string
The price descriptive string, if any.
modified string
The date & time the event was last modified.
performers
A list of performers associated with the event. Each performer entry has the following structure:
id string
The performer ID. Refers to the record in the performers section.
url string
The URL to this performer's page on Eventful.com.
name string
The full name of this performer.
short_bio string
A short description of the performer.
linker string
The Eventful user who linked this performer to this event.
image
An image associated with the event, with the following structure:
url string
The default image URL.
width integer
The default image width, in pixels.
height integer
The default image height, in pixels.
size (e.g. 'thumb')
Details for this image in a specific size, including:
url string
The default image URL.
width integer
The default image width, in pixels.
height integer
The default image height, in pixels.
categories
A list of categories this event is part of. Each category entry has the following structure:
id string
The ID of this category. (Does not change over time.)
name string
The display name of this category. (May change.)
tags
A list of tags (user-generated categories) associated with the event. Each tag entry has the following structure:
id string
The tag ID. (Useful for URLs.)
title string
The tag as it should be displayed.
owner string
The username who created this tag
links
A list of links associated with the event. Each link entry has the following structure:
url string
The URL of this link.
type string
The link type string.
description string
The link description.
username string
The username of the owner this link
time string
Time the Link was added in ISO 8601 format (e.g. "2005-03-01 19:00:00")

See the full list of event fields for more detail.

Venues

<venue>
  <id>V0-001-000102555-5</id>
  <url>http://eventful.com/boston/venues/house-of-blues-boston-/V0-001-000102555-5</url>
  <name>House of Blues - Boston</name>
  <description></description>
  <venue_type>Concert Hall</venue_type>
  <venue_display>1</venue_display>
  <address>15 Lansdowne Street</address>
  <city>Boston</city>
  <tz_olson_path>America/New_York</tz_olson_path>
  <region>Massachusetts</region>
  <region_abbr>MA</region_abbr>
  <postal_code>02215</postal_code>
  <country>United States</country>
  <country_abbr2>US</country_abbr2>
  <country_abbr>USA</country_abbr>
  <latitude>42.347389</latitude>
  <longitude>-71.09572</longitude>
  <geocode_type>EVDB Geocoder</geocode_type>
  <created>2005-04-29 18:21:33</created>
  <modified>2009-04-20 05:22:03</modified>
  <owner>ben88</owner>
  <withdrawn>0</withdrawn>
  <withdrawn_note></withdrawn_note>
  <tags>
    <tag id="boston">
      <title>Boston</title>
      <owner>ben88</owner>
    </tag>
    <tag id="houseofblues">
      <title>House of Blues</title>
      <owner>ben88</owner>
    </tag>
  </tags>
  <image>
    <url>http://images.evdb.com/images/small/I0-001/001/577/403-8.jpeg</url>
    <width>48</width>
    <height>48</height>
    <caption></caption>
    <thumb>
      <url>http://images.evdb.com/images/thumb/I0-001/001/577/403-8.jpeg</url>
      <width>48</width>
      <height>48</height>
    </thumb>
    <small>
      <url>http://images.evdb.com/images/small/I0-001/001/577/403-8.jpeg</url>
      <width>48</width>
      <height>48</height>
    </small>
    <medium>
      <url>http://images.evdb.com/images/medium/I0-001/001/577/403-8.jpeg</url>
      <width>128</width>
      <height>128</height>
    </medium>
  </image>
  <links>
    <link id="15909112">
      <url>http://www.stubpass.com/venue/house-of-blues-boston/</url>
      <type>Tickets</type>
      <description>Buy House Of Blues Tickets</description>
      <username>CRyan</username>
      <time>2009-03-27 13:32:58</time>
    </link>
    <link id="16599295">
      <url>http://ticketsus.at/eventful?CTY=39&amp;DURL=http://www.ticketmaster.com/House-of-Blues-Boston-tickets-Boston/venue/9044?camefrom=CFC_BUYAT&amp;brand=</url>
      <type>Tickets</type>
      <description>Buy Tickets at Ticketmaster.com!</description>
      <username>evdb</username>
      <time>2009-04-20 05:22:03</time>
    </link>
  </links>
</venue>

Key Venue Fields

id string
The unique ID for this venue.
url string
The URL for this venue's page on eventful.com.
name string
The name of the venue.
description string
The venue description.
venue_type string
The type of venue (Arena, Restaurant, Park, etc.)
venue_display boolean
Whether or not the venue name should be displayed in certain cirumstances. Eventful's notion of a venue is a bit broader than you might think. For example, events for which only the postal code is known have a venue named "Postal code 46311, US", for instance. In these cases, a traditional address block looks a bit unusual, and Eventful chooses not to display the venue name in these cases. You may wish to do the same, and the venue_display parameter allows you to do that.
address string
The venue's street address.
city string
The city where the venue is located.
tz_olson_path string
The venue's timezone, as listed in the Olson timezones database (e.g. "America/New_York").
region string
The region where the venue is located. A "region" is an Eventful general term for sub-country political divisions like States, Provinces, Cantons, etc.
postal_code string
The postal code for the venue.
country string
The country name for the venue.
country_abbr2 string
The 2-letter country abbreviation for the venue.
country string
The 3-letter country abbreviation for the venue.
latitude signed float
The venue latitude.
longitude signed float
The venue longitude.
geocode_type string
The method used to geocode the venue latitude and longitude. "EVDB Geocoder" indicates that address-level data was used, and other levels are indicated specifically. (e.g. "City-level Geocoder")
created string
A time stamp in ISO 8601 format (e.g. "2005-03-01 19:00:00") indicating when this venue was created.
modified string
A time stamp in ISO 8601 format (e.g. "2005-03-01 19:00:00") indicating when this venue was last updated.
owner string
The Eventful user name of the user who created (or currently has control of) this venue.
withdrawn boolean
Indicates whether this venue has been "withdrawn" or not. "1" indicates TRUE, "0" indicates FALSE.
withdrawn_note string
A note indicating why the venue has been withdrawn. (e.g. "Closed")
tags
A list of tags (user-generated categorization) associated with the venue. Each tag item has the following structure:
stringstring
The tag string itself.
user string
Thei username who created this tag
image
An image associated with the venue, with the following structure:
url string
The default image URL.
width integer
The default image width, in pixels.
height integer
The default image height, in pixels.
size (e.g. 'thumb')
Details for this image in a specific size, including:
url string
The default image URL.
width integer
The default image width, in pixels.
height integer
The default image height, in pixels.
links
A list of links associated with the venue. Each link item has the following structure:
url string
The URL of this link.
type string
The link type string.
description string
The link description.
username string
The username of the owner this link
time string
Time the Link was added in ISO 8601 format (e.g. "2005-03-01 19:00:00")

Performers

<performer>
  <id>P0-001-000011472-8</id>
  <url>http://eventful.com/performers/3oh3-/P0-001-000011472-8</url>
  <name>3OH!3</name>
  <short_bio>Rock / Electronica / Thrash</short_bio>
  <long_bio></long_bio>
  <created>2006-11-08 15:00:49</created>
  <modified>2009-04-20 13:13:34</modified>
  <creator>PhotoFinishRecords</creator>
  <demand_count>2310</demand_count>
  <demand_member_count>9919</demand_member_count>
  <event_count>66</event_count>
  <withdrawn>0</withdrawn>
  <withdrawn_note></withdrawn_note>
  <tags>
    <tag id="concerts">
      <title>concerts</title>
      <owner>bobfather</owner>
    </tag>
    <tag id="electronica">
      <title>electronica</title>
      <owner>chris_radcliff</owner>
    </tag>
    <tag id="music">
      <title>music</title>
      <owner>kaitz95801</owner>
    </tag>
    <tag id="rock">
      <title>rock</title>
      <owner>chris_radcliff</owner>
    </tag>
  </tags>
  <image>
    <url>http://static.eventful.com/images/small/I0-001/001/740/197-8.png</url>
    <width>48</width>
    <height>48</height>
    <caption></caption>
    <thumb>
      <url>http://static.eventful.com/images/thumb/I0-001/001/740/197-8.png</url>
      <width>48</width>
      <height>48</height>
    </thumb>
    <small>
      <url>http://static.eventful.com/images/small/I0-001/001/740/197-8.png</url>
      <width>48</width>
      <height>48</height>
    </small>
    <medium>
      <url>http://static.eventful.com/images/medium/I0-001/001/740/197-8.png</url>
      <width>128</width>
      <height>128</height>
    </medium>
  </image>
  <links>
    <link id="120675">
      <url>http://www.myspace.com/3oh3</url>
      <type>MySpace</type>
      <description>Official MySpace</description>
      <username>anthony760</username>
      <time>2008-09-10 12:01:36.94735</time>
    </link>
    <link id="122437">
      <url>http://3oh3.com</url>
      <type>Official Site</type>
      <description>3oh3.com</description>
      <username>anthony760</username>
      <time>2008-09-26 12:09:22.431333</time>
    </link>
  </links>
</performer>

Key Performer Fields

id string
The unique ID for this performer.
url string
The page URL for this performer on eventful.com.
name string
The full name of this performer.
short_bio string
A short description of this performer.
long_bio string
A detailed biography of this performer.
created datetime
The date & time the performer was initially created. (e.g. '2006-03-17 16:55:00')
modified datetime
The date & time the performer was last updated. (e.g. '2006-03-17 16:55:00')
creator string
The Eventful username of the performer's owner.
demand_count integer
The number of demands for this performer.
demand_member_count integer
The number of people who joined demands for this performer.
event_count integer
The number of events involving this performer.
withdrawn boolean
True if this performer has been marked as withdrawn.
withdrawn_note string
If this performer has been marked as withdrawn, a short reason why.
tags
A list of tags (user-generated categorization) associated with the performer. Each tag item has the following structure:
stringstring
The tag string itself.
user string
Thei username who created this tag
image
An image associated with the performer, with the following structure:
url string
The default image URL.
width integer
The default image width, in pixels.
height integer
The default image height, in pixels.
size (e.g. 'thumb')
Details for this image in a specific size, including:
url string
The default image URL.
width integer
The default image width, in pixels.
height integer
The default image height, in pixels.
links
A list of links associated with the performer. Each link item has the following structure:
url string
The URL of this link.
type string
The link type string.
description string
The link description.
username string
The username of the owner this link
time string
Time the Link was added in ISO 8601 format (e.g. "2005-03-01 19:00:00")