Marcato Festival XML Feed Guide

This guide will go through each of the Marcato Festival XML feeds and break them down, field by field, with any important notes or examples. If you have any questions, please email support@marcatodigital.com

We also have a set of scripts that can be used to take the XML feeds and convert them into PHP objects to be manipulated and displayed on a festival's website. These scripts also include a basic caching system, and can either be dropped right into your site as-is, or modified to meet your festival's specific requirements. They can also serve as a good reference if you plan on rolling your own custom integration. Check it out here: http://github.com/morgancurrie/marcato_festival_website_integration

If there are any other fields from the app that aren't present in the feeds, just drop us a line and we'll add them for you.

Note: an asterisk (*) after a field name means the field is required in-app, so it will always contain a value. All other fields are optional and may be blank, including any nested arrays.


There are XML feeds available for: Artists, Artist Types, Shows, Workshops, Workshop Types, Venues



back to top
Artists Feed (example: http://marcatoweb.com/xml/artists_8.xml)

You can use the information in this feed to display a complete artist listing with links to individual artist profiles. Basic show/workshop information is included for each artist, which can be used together with the other feeds to create links between artists and events.

Field Name Description Type Example / Notes
name * The artist's name String
id * The database ID of the artist Integer This is referenced in Show/Workshop feeds in their respective Performance/Presentation arrays. This can be used to create links between artists and events, etc.
bio_public The artist's main biography, labelled "Biography" in-app String Newlines are stored as \n, so you'll have replace them with <br /> tags to preserve formatting on the web.
bio_limited The artist's shorter biography, labelled "Short Bio" in-app String Newlines are stored as \n, so you'll have replace them with <br /> tags to preserve formatting on the web.
homebase The artist's home base String This is used to display a custom location for each artist (eg. "Canada", "Nova Scotia", "Cape Breton") as opposed to their actual address.
web_photo_url The URL of the artist's full size web-optimized image String The value of this field will be a complete URL, eg. http://marcatoapp.com/artists_files/web_photos/61091/original.jpg, except the extension (".jpg") will match whatever the image was originally uploaded as.

Thumbnails and various sizes of the image are automatically created on upload. You can replace the 'original.[extension]' with the following options to use different photos:

  • web.jpg is a proportionally resized version, which will grow to 300x300, but since it retains proportions, a really wide image may end up being only 300x180, etc.
  • medium_square.jpg is a 288x288 cropped-to-fit thumbnail, so while the width/height is guaranteed, the cropping may occasionally cut out part of the image.
  • small_square.jpg is a 140x140 cropped-to-fit thumbnail.
  • thumb.png is a 100x100 cropped-to-fit thumbnail.
  • tiny_square.jpg is a 40x40 cropped-to-fit thumbnail.
web_photo_url_root The URL of the artist's web-optimized image, minus the filename String This field is useful if you plan on displaying various image sizes, as it'll save you from removing the original filename with a regex. You can add 'web.jpg' to this value to get the full path to the 300x300 version of the image.
web_photo_fingerprint A token you can use to check if an image has been updated String This field changes any time a photo is updated/replaced. By instructing browsers and proxies to only download updated versions of cached assets we can further speed things up.
photo_url The URL of the artist's full quality press photo String The value of this field will be a complete URL, eg. http://marcatoapp.com/artists_files/photos/61091/original.jpg, except the extension (".jpg") will match whatever the image was originally uploaded as.

Thumbnails and various sizes of the image are automatically created on upload. You can replace the 'original.[extension]' with the following options to use different photos:

  • web_compressed.jpg is a proportionally resized version, which will grow to 300x300, but since it retains proportions, a really wide image may end up being only 300x180, etc.
  • thumb.png is a 100x100 cropped-to-fit thumbnail, so while the width/height is guaranteed, the cropping may occasionally cut out part of the image.

Please note: as press photos tend to be super high quality, it's recommended that you use the web-optimized version when possible
photo_url_root The URL of the artist's press photo, minus the filename String This field is useful if you plan on displaying various image sizes, as it'll save you from removing the original filename with a regex. You can add 'web_compressed.jpg' to this value to get the full path to the 300x300 version of the image.
photo_fingerprint A token you can use to check if an image has been updated String This field changes any time a photo is updated/replaced. By instructing browsers and proxies to only download updated versions of cached assets we can further speed things up.
website The artist's website String This field will include the first website added to the artist profile. If you'd like to display multiple links for each artist, see the 'Website Array' section of this feed.
updated_at The unformatted date/time that this object was last updated Datetime eg. 2011-11-18T11:28:35-04:00

Show Array (each artist may have one or more shows)
id *
 The database ID of the show Integer You can use this to link to each individual show through the shows feed.
name *
 The name of the show String
show_on_website
Display this on the public website? Boolean If this value of this field is 'false', and you are displaying this information on a public site/app, you shouldn't display this record.
date *
 The unformatted date of the show Date eg. 2011-08-27
formatted_date *
 A formatted version of the date String eg. "August 27th (Sat)"
formatted_start_time
A formatted version of the start time String eg. "7:30 PM"
formatted_end_time
A formatted version of the end time String eg. "1:30 AM"
date_unix *
 A UNIX timestamp of the show date String eg. "1321401600"
start_time_unix
A UNIX timestamp of the show start time String eg. "946755000"
end_time_unix
A UNIX timestamp of the show end time String eg. "946755000"
venue_name
The name of the show's venue Integer eg. "Governor's Peanut Bar"

Workshop Array (each artist may have one or more workshops)
id *
 The database ID of the workshop Integer You can use this to link to each individual workshop through the workshops feed.
name *
 The name of the workshop String
show_on_website
Display this on the public website? Boolean If this value of this field is 'false', and you are displaying this information on a public site/app, you shouldn't display this record.
date *
 The unformatted date of the workshop Date eg. 2011-08-27
formatted_date *
 A formatted version of the date String eg. "August 27th (Sat)"
formatted_start_time
A formatted version of the start time String eg. "7:30 PM"
formatted_end_time
A formatted version of the end time String eg. "1:30 AM"
date_unix *
 A UNIX timestamp of the workshop date String eg. "1321401600"
start_time_unix
A UNIX timestamp of the workshop start time String eg. "946755000"
end_time_unix
A UNIX timestamp of the workshop end time String eg. "946755000"
venue_name
The name of the workshop's venue Integer eg. "Mabou Arts & Crafts Center"

Website Array (each artist may have one or more websites)
name *
 The name of the website String eg. "MySpace"
url *
 The URL of the website String eg. "http://myspace.com/tomfunorchestra"

Tags "Categories" Array (please note: tags are labelled as 'categories' in our XML feeds)
category *
 The name of the tag String eg. "my custom tag"




back to top
Artist Types Feed (example: http://marcatoweb.com/xml/artist_types_8.xml)

You can use the information in this feed along with the artists feed to group and display artists by their types. Artist types are completely optional.

Field Name Description Type Example / Notes
name * The name of the artist type String eg. "Rock"
id * The database ID of the artist type Integer This is can be used along with the artist feed to group and display artists by their various types.




back to top
Shows Feed (example: http://marcatoweb.com/xml/shows_8.xml)

You can use the information in this feed to display a complete show listing with links to individual show descriptions. Artist lineups are included for each show, which can be used together with the artist feed to create links between shows and artists.

Field Name Description Type Example / Notes
name * The show's name String
id * The database ID of the show Integer This can be used to create links between shows and performing artists.
date * The unformatted date of the show Date eg. 2011-08-27
formatted_date * A formatted version of the date String eg. "August 27th (Sat)"
venue_name The name of the show's venue String Shows are not required to have venues, so this can be blank occasionally.
formatted_start_time A formatted version of the start time String eg. "7:30 PM"
formatted_end_time A formatted version of the end time String eg. "1:30 AM"
formatted_door_time A formatted version of the door time String eg. "1:30 AM"
date_unix * A UNIX timestamp of the date String eg. "1321401600"
start_time_unix A UNIX timestamp of the start time String eg. "946755000"
end_time_unix A UNIX timestamp of the end time String eg. "946755000"
door_time_unix A UNIX timestamp of the door time String eg. "946755000"
facebook_link Facebook event link String If the show has been pushed to Facebook via Marcato, this field will contain a link to the associated FB event.
description_public The full description of the show String Newlines are stored as \n, so you'll have replace them with <br /> tags to preserve formatting on the web.
description_web A website-specific version of the description String Some festivals may just use the full description field, leaving this one blank.
ticket_info Information about show tickets String eg. "Call the Civic Centre Box Office: 625-2591"
ticket_link A link to buy tickets online String eg. "http://ticketmaster.com/buy/tickets"
ticket_status The value of the 'Tickets' dropdown String eg. "Available", "Box Office Only", "Sold Out"
seating The value of the 'Seating' dropdown String eg. "General Admission", "Reserved Seating"
price The price of the show String eg. "$60 advance, $75 at the door"
poster_url The URL of the show's poster/image String The value of this field will be a complete URL, eg. http://marcatoapp.com/shows_files/posters/7381/original.png, except the extension (".jpg") will match whatever the image was originally uploaded as.

Thumbnails and various sizes of the image are automatically created on upload. You can replace the 'original.[extension]' with the following options to use different images:

  • web.png is a proportionally resized version, which will grow to 300x300, but since it retains proportions, a really wide image may end up being only 300x180, etc.
  • thumb.png is a 100x100 cropped-to-fit thumbnail, so while the width/height is guaranteed, the cropping may occasionally cut out part of the image.
poster_url_root The URL of the shows's poster/image, minus the filename String This field is useful if you plan on displaying various image sizes, as it'll save you from removing the original filename with a regex. You can add 'web.png' to this value to get the full path to the 300x300 version of the image.
poster_fingerprint A token you can use to check if an image has been updated String This field changes any time a poster is updated/replaced. By instructing browsers and proxies to only download updated versions of cached assets we can further speed things up.
updated_at The unformatted date/time that this object was last updated Datetime eg. 2011-11-18T11:28:35-04:00

Venue Array (a show can only have one venue)
name *
 The name of the venue String eg. "Governor's Peanut Bar"
id *
 The database ID of the venue Integer This is can be used along with the venues feed to link to full venue profiles.
street
The street address of the venue String eg. "29 Main St."
city
The city of the venue String eg. "Sydney"
province_state
The province/state of the venue String eg. "Nova Scotia"
country
The country of the venue String eg. "Canada"
postal_code
The postal code of the venue String eg. "B1P 2Z9"
community
The community the venue is located in String eg. "The North End"
website
The website of the venue String eg. "http://thevenue.com"
longitude
The longitude of the venue's address (comes from Google maps) Decimal eg. 46.1034079
latitude
The latitude of the venue's address (comes from Google maps) Decimal eg. 46.1034079

Performances Array (each show may have one or more performances)
id *
 The database ID of the performance Integer Please note: multiple artists sharing a single performance will appear as multiple performances with the same ID.
artist *
 The name of the performing artist String eg. "The Yarnells"
artist_id *
 The database ID of the artist Integer This is can be used along with the artists feed to link to full artist profiles.
start
A formatted version of the start time for the performance String eg. "10:15 PM"
end
A formatted version of the end time for the performance String eg. "11:00 PM"
rank
The website rank of the performance String This field is used to order the performances in a custom order, with '1' being the first performance displayed. This field is optional, but if any performances have a rank, you should only display other performances with ranks.

Tags "Categories" Array (please note: tags are labelled as 'categories' in our XML feeds)
category *
 The name of the tag String eg. "my custom tag"




back to top
Workshops Feed (example: http://marcatoweb.com/xml/workshops_8.xml)

You can use the information in this feed to display a complete workshop listing with links to individual workshop descriptions. Presenters are included for each workshop, which can be used together with the artist feed to create links between workshops and artists.

Field Name Description Type Example / Notes
name * The workshop's name String
id * The database ID of the workshop Integer This can be used to create links between workshops and presenters.
date * The unformatted date of the workshop Date eg. 2011-08-27
formatted_date * A formatted version of the date String eg. "August 27th (Sat)"
venue_name The name of the workshop's venue String Workshops are not required to have venues, so this can be blank occasionally.
formatted_start_time A formatted version of the start time String eg. "7:30 PM"
formatted_end_time A formatted version of the end time String eg. "1:30 AM"
date_unix * A UNIX timestamp of the date String eg. "1321401600"
start_time_unix A UNIX timestamp of the start time String eg. "946755000"
end_time_unix A UNIX timestamp of the end time String eg. "946755000"
door_time_unix A UNIX timestamp of the door time String eg. "946755000"
facebook_link Facebook event link String If the workshop has been pushed to Facebook via Marcato, this field will contain a link to the associated FB event.
description_public The full description of the workshop String Newlines are stored as \n, so you'll have replace them with <br /> tags to preserve formatting on the web.
description_web A website-specific version of the description String Some festivals may just use the full description field, leaving this one blank.
ticket_info Information about workshop tickets String eg. "Call the Civic Centre Box Office: 625-2591"
ticket_link A link to buy tickets online String eg. "http://ticketmaster.com/buy/tickets"
ticket_status The value of the 'Tickets' dropdown String eg. "Available", "Box Office Only", "Sold Out"
seating The value of the 'Seating' dropdown String eg. "General Admission", "Reserved Seating"
price The price of the workshop String eg. "$60 advance, $75 at the door"
poster_url The URL of the workshop's poster/image String The value of this field will be a complete URL, eg. http://marcatoapp.com/workshops_files/posters/7381/original.png, except the extension (".jpg") will match whatever the image was originally uploaded as.

Thumbnails and various sizes of the image are automatically created on upload. You can replace the 'original.[extension]' with the following options to use different images:

  • web.png is a proportionally resized version, which will grow to 300x300, but since it retains proportions, a really wide image may end up being only 300x180, etc.
  • thumb.png is a 100x100 cropped-to-fit thumbnail, so while the width/height is guaranteed, the cropping may occasionally cut out part of the image.
poster_url_root The URL of the workshops's poster/image, minus the filename String This field is useful if you plan on displaying various image sizes, as it'll save you from removing the original filename with a regex. You can add 'web.png' to this value to get the full path to the 300x300 version of the image.
poster_fingerprint A token you can use to check if an image has been updated String This field changes any time a poster is updated/replaced. By instructing browsers and proxies to only download updated versions of cached assets we can further speed things up.
event_contact_summary Event Contact details String If there is a contact associated with the workshop with a role of 'Event Contact', their contact information will appear in this field, eg. "John Doe (Some Organization) - (555) 555-555 - johndoe@gmail.com"
event_contact_name The event contact's title String If there is a contact associated with the workshop with a role of 'Event Contact', their name and company will appear in this field, eg. "John Doe (Some Organization)"
event_contact_email The event contact's email String If there is a contact associated with the workshop with a role of 'Event Contact', their email address will appear in this field, eg. "johndoe@gmail.com"
event_contact_phone The event contact's phone String If there is a contact associated with the workshop with a role of 'Event Contact', their phone number will appear in this field, eg. "(555) 555-555"
hosting_organization_title The title of the Hosting Organization String If there is a contact associated with the workshop with a role of 'Hosting Organization', their title will appear in this field, eg. "Bras d'Or Yacht Club"
updated_at The unformatted date/time that this object was last updated Datetime eg. 2011-11-18T11:28:35-04:00

Workshop Types Array (a workshop can belong to one or more workshop types)
name *
 The name of the workshop type String eg. "Group Music Lesson"
id *
 The database ID of the workshop type Integer This is can be used along with the workshop_types feed to group and display workshops by their various types

Venue Array (a workshop can only have one venue)
name *
 The name of the venue String eg. "Governor's Peanut Bar"
id *
 The database ID of the venue Integer This is can be used along with the venues feed to link to full venue profiles
street
The street address of the venue String eg. "29 Main St."
city
The city of the venue String eg. "Sydney"
province_state
The province/state of the venue String eg. "Nova Scotia"
country
The country of the venue String eg. "Canada"
postal_code
The postal code of the venue String eg. "B1P 2Z9"
community
The community the venue is located in String eg. "The North End"
website
The website of the venue String eg. "http://thevenue.com"
longitude
The longitude of the venue's address (comes from Google maps) Decimal eg. 46.1034079
latitude
The latitude of the venue's address (comes from Google maps) Decimal eg. 46.1034079

Presentations Array (each workshop may have one or more presentations)
id *
 The database ID of the presentation Integer Please note: multiple artists sharing a single presentation will appear as multiple presentations with the same ID.
presenter *
 The name of the presenting artist String eg. "The Yarnells"
presenter_id *
 The database ID of the presenting artist Integer This is can be used along with the artists feed to link to full artist profiles.
start
A formatted version of the start time for the presentation String eg. "10:15 PM"
end
A formatted version of the end time for the presentation String eg. "11:00 PM"
rank
The website rank of the presentation String This field is used to order the presentations in a custom order, with '1' being the first presentation displayed. This field is optional, but if any presentations have a rank, you should only display other presentations with ranks.
presenter_type
The type of presenter String Workshop presentations can have both artists and contacts associated with them, but currently we only include artists in the XML feeds, so this will always equal 'artist'

Tags "Categories" Array (please note: tags are labelled as 'categories' in our XML feeds)
category *
 The name of the tag String eg. "my custom tag"




back to top
Workshop Types Feed (example: http://marcatoweb.com/xml/workshop_types_8.xml)

You can use the information in this feed along with the workshops feed to group and display workshops by their types. Workshop types are completely optional.

Field Name Description Type Example / Notes
name * The name of the workshop type String eg. "Group Music Lesson"
id * The database ID of the workshop type Integer This is can be used along with the workshop feed to group and display workshops by their various types.




back to top
Venues Feed (example: http://marcatoweb.com/xml/venues_8.xml)

You can use the information in this feed to display a complete venue listing with links to individual venue descriptions.

Field Name Description Type Example / Notes
name * The name of the venue String eg. "Governor's Peanut Bar"
id * The database ID of the venue Integer This is referenced in both show and workshop feeds.
street The street address of the venue String eg. "29 Main St."
city The city of the venue String eg. "Sydney"
province_state The province/state of the venue String eg. "Nova Scotia"
country The country of the venue String eg. "Canada"
postal_code The postal code of the venue String eg. "B1P 2Z9"
community The community the venue is located in String eg. "The North End"
longitude The longitude of the venue's address (comes from Google maps) Decimal eg. 46.1034079
latitude The latitude of the venue's address (comes from Google maps) Decimal eg. 46.1034079
primary_phone_number The phone number for the venue String eg. "(555) 555-1234"
photo_url The URL of the venue's photo String The value of this field will be a complete URL, eg. http://marcatoapp.com/venues_files/photos/1234/original.png, except the extension (".jpg") will match whatever the image was originally uploaded as.

Thumbnails and various sizes of the image are automatically created on upload. You can replace the 'original.[extension]' with the following options to use different images:

  • web.png is a proportionally resized version, which will grow to 300x300, but since it retains proportions, a really wide image may end up being only 300x180, etc.
  • thumb.png is a 100x100 cropped-to-fit thumbnail, so while the width/height is guaranteed, the cropping may occasionally cut out part of the image.
photo_url_root The URL of the venue's photo, minus the filename String This field is useful if you plan on displaying various image sizes, as it'll save you from removing the original filename with a regex. You can add 'web.png' to this value to get the full path to the 300x300 version of the image.
photo_fingerprint A token you can use to check if an image has been updated String This field changes any time a photo is updated/replaced. By instructing browsers and proxies to only download updated versions of cached assets we can further speed things up.
updated_at The unformatted date/time that this object was last updated Datetime eg. 2011-11-18T11:28:35-04:00

Show Array (each venue may have one or more shows)
id *
 The database ID of the show Integer You can use this to link to each individual show through the shows feed.
name *
 The name of the show String
show_on_website
Display this on the public website? Boolean If this value of this field is 'false', and you are displaying this information on a public site/app, you shouldn't display this record.
date *
 The unformatted date of the show Date eg. 2011-08-27
formatted_date *
 A formatted version of the date String eg. "August 27th (Sat)"
formatted_start_time
A formatted version of the start time String eg. "7:30 PM"
formatted_end_time
A formatted version of the end time String eg. "1:30 AM"

Workshop Array (each venue may have one or more workshops)
id *
 The database ID of the workshop Integer You can use this to link to each individual workshop through the workshops feed.
name *
 The name of the workshop String
show_on_website
Display this on the public website? Boolean If this value of this field is 'false', and you are displaying this information on a public site/app, you shouldn't display this record.
date *
 The unformatted date of the workshop Date eg. 2011-08-27
formatted_date *
 A formatted version of the date String eg. "August 27th (Sat)"
formatted_start_time
A formatted version of the start time String eg. "7:30 PM"
formatted_end_time
A formatted version of the end time String eg. "1:30 AM"

Tags "Categories" Array (please note: tags are labelled as 'categories' in our XML feeds)
category *
 The name of the tag String eg. "my custom tag"

Website Array (each venue may have one or more websites)
name *
 The name of the website String eg. "MySpace"
url *
 The URL of the website String eg. "http://thevenue.com"