Tools

Technical Reference

Wise words

"Always listen to experts. They'll tell you what can't be done, and why. Then do it."

- Robert A. Heinlein

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.

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.

The page URL for this event on eventful.com.

title string

The event title.

description string

The event description.

start_time string

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.

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.