XML Feed FAQ


I hate XML, do you have anything else?

Can you provide your data in JSON format?

We now offer an option for JSON feeds as well as the standard XML. It is just in beta testing, but so far no known issues.

I love XML, do you have a schema definition?

Can you provide an xsd schema file

Each feed is customized so we don't have an official xsd file but we have created 2 sample xsd files for a typical feed here
and for a feed with the recurrence and multiple images options turned on here

Why should I bother with an XML feed?

What is the difference between an XML feed and the normal API calls?

The format of the xml coming back is about the same as the format of the API (with a few minor differences). The biggest difference between the API and feeds is the API is returning data in real time, where as the feeds are based on a snapshot of data taken at midnight. The advantage of the xml feeds is that you get all the data in one file, with the API you will need to page through multiple calls to get the data you want.

What will be the size of an xml file?

How much data will I have to parse in xml?

Feed sizes vary greatly based on the timeframe, geography and options used. For a typical full USA feed (all future, standard config) the compressed xml is usually around 250MB and uncompressed around 1.5Gb. A similar worldwide feed is about 500MB compressed and 3.5Gb uncompressed. We recommend using a Sax based xml parser since they will handle the large amounts of data better.

I tried to download the feed and I got a 404 file not found error.

When can I download the feed?

We recommend that you try to download your feed files starting at around 6am PST. If you get a 404 then just keep trying to download the file every 15 minutes until you are able to get it. We have many different customers with very different sets of data being generated all running on just a few export boxes. Each feed is randomly scheduled for one box and depending on when it starts, what other feeds are running, the general load of the box your feed might finish as early as 1am PST, or as late as 10am. In general most feeds have finished by around 6am PST so that is a good time to start checking.

I see some events with a @ in the event_id.

What does the @ mean in an event_id?

Event id's will have an @ in them if they are a recurring event. The id before the @ is the normal event id, the numbers after the @ is the date for the next specific recurrence of the event. The date is in the form of YYYYMMDDHH. To get a list of the recurrences your feed needs either the option to list the instances, or the option to give you the recurrence rules (see below).

I don't see any timezone information in the feed.

What is the timezone for an event?

The start_time and stop_time fields are provided in "floating" time, which should be interpreted as "the time appropriate for the venue." In most cases the times are from local event sites or promoters, so the time zone is not provided. We don't make any guesses about the time zone, because the "floating" time is exactly what a local would expect.

How do I parse the recurrence rules?

What is the structure for the recurrence rules <rrule>?

A good overview of the rrule can be found here

My xml parser never does anything, it just sits there.

Which type of xml parser should I use?

Since our xml data can be very large we recommend using a Sax parser. A sax parser will process each event/performer/venue record one at a time. If you use a DOM style parser the code will try to read the entire xml document into memory and this is often not possible (or at the very least will be very slow). Using a Sax parser will only have one event/performer/venue record in memory at a time so will not run out of memory. The downside to this parser is as you are reading the event records you will not have access to the venue records (where the lat/long, address, etc is stored). The venue_id is stored in the event record but the actual venue data (lat/long, address etc) is not available until later when the venue records are parsed.

Why can't I find the lat/long of an event?

Where are all the missing event fields like lat/long address, etc?

The xml feed is broken up into 3 sections - the <events> with multiple individual event records, the <venues> section with individual venue records and finally the <performers> section with individual performer records. For any given event record it will have a <venue_id> field that can be used to tie to the specific venue record so the lat/long, address etc can be found for the event. There is also a performers element in the event record which will list any performer_id's known for the event. The performer_id can then be used to lookup the correct performer record from the performers section.

I need to know all the different categories there are.

What are all the different categories and sub categories Eventful has?

id name alias
music Concerts & Tour Dates Concerts
music_blues Concerts & Tour Dates: Blues Blues
music_classical Concerts & Tour Dates: Classical Classical
music_country Concerts & Tour Dates: Country Country
music_dance Concerts & Tour Dates: Dance Dance
music_easy_listening Concerts & Tour Dates: Easy Listening Easy Listening
music_electronic Concerts & Tour Dates: Electronic Electronic
music_folk Concerts & Tour Dates: Folk Folk
music_jazz Concerts & Tour Dates: Jazz Jazz
music_latin Concerts & Tour Dates: Latin Latin
music_newage Concerts & Tour Dates: New Age New Age
music_opera Concerts & Tour Dates: Opera Opera
music_rb Concerts & Tour Dates: R&B/Soul R&B/Soul
music_reggae Concerts & Tour Dates: Reggae Reggae
music_vocal Concerts & Tour Dates: Vocal Vocal
music_rap_hiphop Concerts & Tour Dates: Hip Hop/Rap Hip Hop/Rap
music_metal Concerts & Tour Dates: Heavy Metal Heavy Metal
music_religious Concerts & Tour Dates: Inspirational Inspirational
music_rock Concerts & Tour Dates: Rock Rock
music_pop Concerts & Tour Dates: Pop Pop
music_world Concerts & Tour Dates: World World
music_alternative Concerts & Tour Dates: Alternative Alternative
music_childrens Concerts & Tour Dates: Children's Children's
conference Conferences & Tradeshows Conferences
conference_career Conferences & Tradeshows: Career Career
conference_convention Conferences & Tradeshows: Convention Convention
conference_seminar Conferences & Tradeshows: Seminar Seminar
conference_talkslectures Conferences & Tradeshows: Talks/Lectures Talks/Lectures
comedy Comedy Comedy
learning_education Education Education
learning_education_classworkshop Education: Class/Workshop Class/Workshop
family_fun_kids Kids & Family Family
festivals_parades Festivals Festivals
festivals_parades_circus Festivals: Circus Circus
festivals_parades_festival Festivals: Festival Festival
festivals_parades_fairs Festivals: Fairs Fairs
festivals_parades_parade Festivals: Parade Parade
movies_film Film Film
movies_film_filmfestival Film: Film Festival Film Festival
food Food & Wine Food
food_beer Food & Wine: Beer Beer
food_wine Food & Wine: Wine Wine
food_farmersmarket Food & Wine: Farmer’s Market Farmer’s Market
food_tastings Food & Wine: Tastings Tastings
fundraisers Fundraising & Charity Fundraisers
fundraisers_blooddrive Fundraising & Charity: Blood Drive Blood Drive
fundraisers_volunteer Fundraising & Charity: Volunteer Volunteer
art Art Galleries & Exhibits Galleries
art_antiques Art Galleries & Exhibits: Antiques Antiques
art_painting Art Galleries & Exhibits: Painting Painting
art_photography Art Galleries & Exhibits: Photography Photography
art_artexhibits Art Galleries & Exhibits: Art Exhibits Art Exhibits
art_artsandcrafts Art Galleries & Exhibits: Arts and Crafts Arts and Crafts
art_fashion Art Galleries & Exhibits: Fashion Fashion
support Health & Wellness Health
support_fitness Health & Wellness: Fitness Fitness
support_seniorhealth Health & Wellness: Senior Health Senior Health
support_support Health & Wellness: Support Support
support_yoga Health & Wellness: Yoga Yoga
holiday Holiday Holiday
books Literary & Books Literary
books_poetry Literary & Books: Poetry Poetry
attractions Museums & Attractions Museums
community Neighborhood Neighborhood
community_library Neighborhood: Library Library
community_holiday Neighborhood: Holiday Holiday
community_seasonal Neighborhood: Seasonal Seasonal
business Business & Networking Networking
singles_social Nightlife & Singles Nightlife
singles_social_trivianight Nightlife & Singles: Trivia Night Trivia Night
singles_social_comedy Nightlife & Singles: Comedy Comedy
singles_social_bars Nightlife & Singles: Bars Bars
singles_social_dating Nightlife & Singles: Dating Dating
singles_social_karaoke Nightlife & Singles: Karaoke Karaoke
singles_social_openmic Nightlife & Singles: Open Mic Open Mic
schools_alumni University & Alumni On Campus
clubs_associations Organizations & Meetups Organizations
outdoors_recreation Outdoors & Recreation Outdoors
outdoors_recreation_cycling Outdoors & Recreation: Cycling Cycling
outdoors_recreation_hiking Outdoors & Recreation: Hiking Hiking
outdoors_recreation_nature Outdoors & Recreation: Nature Nature
outdoors_recreation_running Outdoors & Recreation: Running Running
performing_arts Performing Arts Performing Arts
performing_arts_cabaret Performing Arts: Cabaret Cabaret
performing_arts_opera Performing Arts: Opera Opera
performing_arts_dance Performing Arts: Dance Dance
performing_arts_musical Performing Arts: Musical Musical
performing_arts_ballet Performing Arts: Ballet Ballet
performing_arts_comedy Performing Arts: Comedy Comedy
performing_arts_theatre Performing Arts: Theatre Theatre
animals Pets Pets
animals_cats Pets: Cats Cats
animals_dogs Pets: Dogs Dogs
politics_activism Politics & Activism Politics
sales Sales & Retail Sales
sales_auction Sales & Retail: Auction Auction
sales_craftshow Sales & Retail: Craft Show Craft Show
sales_fleamarket Sales & Retail: Flea Market Flea Market
sales_yardsale Sales & Retail: Yard Sale Yard Sale
sales_retail Sales & Retail: Retail Retail
science Science Science
religion_spirituality Religion & Spirituality Spirituality
sports Sports Sports
sports_autoracing Sports: Auto Racing Auto Racing
sports_dance Sports: Dance Dance
sports_gymnastics Sports: Gymnastics Gymnastics
sports_iceskatingskiing Sports: Ice Skating/Skiing Ice Skating/Skiing
sports_softball Sports: Softball Softball
sports_swimmingdiving Sports: Swimming/Diving Swimming/Diving
sports_volleyball Sports: Volleyball Volleyball
sports_baseball Sports: Baseball Baseball
sports_basketball Sports: Basketball Basketball
sports_cricket Sports: Cricket Cricket
sports_football Sports: Football Football
sports_golf Sports: Golf Golf
sports_hockey Sports: Hockey Hockey
sports_rugby Sports: Rugby Rugby
sports_soccer Sports: Soccer Soccer
sports_tennis Sports: Tennis Tennis
sports_wrestling Sports: Wrestling Wrestling
technology Technology Technology
technology_computer Technology: Computer Computer
other Other & Miscellaneous Other

Now that I know the categories what are the venue types?

What are all the different venue types Eventful has?

Venue Type id
Airport 35
Ampitheatre 24
Arena 17
Art Gallery 14
Athletic Field 22
Auditorium 40
Bar/Night Club 39
Beach 20
Bistro 3
Bookstore 27
Bridge 26
Business 34
Camp 32
Cinema 12
City 45
Coffee House 2
Community Center 31
Concert Hall 1
Convention Center 5
Country 44
Court House 16
Factory 33
Gallery 42
Government Building 48
Gymnasium 21
Hotel 30
Library 49
Marina 19
Market 50
Meeting Hall 38
Military Base 58
Museum 41
Office Building 23
Online 28
Outdoors: City Street 36
Outdoors: Field 51
Outdoors: Rural 37
Outdoors: Waterfront 52
Park 18
Parking Lot 8
Place of Worship 29
Postal Code 43
Private Residence 9
Public Square 15
Radio 56
Region 46
Research Institution 54
Restaurant 4
Retail Store 7
School 11
Shopping Mall 53
Stadium 6
Television 57
Theatre (Live Stage) 13
University 10
University/College Department 55
Water Vessel 25
World 47

I don't know how to parse the xml feed file.

Is there a sample code sample that does parsing?

Parsing the xml is going to depend on what you want done with the data. Below are two sample programs that at least process each element and print it out to the screen. For your code you'll have to decide what you want to do with the data, and how you want to tie the different xml sections together (Event record to venue record for example).
First is sample python code that parses an xml file and prints out the element type and its value
import xml.sax

class XMLContentHandler(xml.sax.ContentHandler):
   element_value = ''
   def __init__(self):
     xml.sax.ContentHandler.__init__(self)
   def startElement(self, name, attrs):
     print("startElement of name => '" + name + "'")
     self.element_value = ''

   def endElement(self, name):
     print("endElement '" + name + "' has value of => '" + self.element_value + "'")

   def characters(self, content):
     self.element_value = self.element_value + content

def main(sourceFileName):
   source = open(sourceFileName)
   xml.sax.parse(source, XMLContentHandler())
  
if __name__ == "__main__":
     main("t.xml")

Next is a sample perl program that pulls out a specific tag and prints the value if --tag is passed in. It will also print out all tags and values if the --alltags flag is used.

#!/usr/bin/perl
use XML::Twig;
use Data::Dumper;
use XML::Simple qw(XMLin);
use Getopt::Long;
use strict;

my ($feed,$tag,$alltags,$fh);

sub print_tag { 
      my( $t, $element)= @_;

      my $tag_text = $element->text;     # get the text
      print "$tag text => $tag_text\n";
      $t->purge;
}


GetOptions(
           'file=s'  => \$feed,
           'tag=s'   => \$tag,
           'alltags' => \$alltags,
          ) or die "invalid argument(s)\n";

$feed ||= shift @ARGV;
$tag  ||= 'description';
if (!$feed) {
  open $fh, '-' or die "can't open stdin : $!\n";
} else {
  if(`gzip -t $feed` == 0) { 
    open($fh, "gunzip -c $feed |") or die "can't open gzipped feed file: $feed: $!\n";
  } else {
    open $fh, '<', $feed or die "can't open feed file: $feed: $!\n";
  }
}
print "Tag is => $tag\n";
my $t= XML::Twig->new( 
           twig_roots   => { $tag => \&print_tag, }, # selected tag
           twig_print_outside_roots => $alltags,     # print the rest
       );
my $results;
my $var = eval {
  $results =  $t->parse( $fh );
};
if ($@) {
  print "XML output file $feed  is corrupt => $@\n";
}
exit 0;