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.
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
And here are two sample json schema definitions using similar sets of data.
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;