Response format

The schema of the returned data is consistent across all festivals, but there are significant variations in the level of data completeness between events and festivals. Where no value is available, the API will return null values - you should ensure your application treats and displays these values as "Unknown" rather than for example as equivalent to a boolean false or numerical zero. Before building any application reliant on a particular field, we strongly recommend exploring the range and availability of values across the festivals you wish to include.

Properties highlighted below are guaranteed to have values for all events.

{
"age_category"
"artist"
"artist_type"
"country"
"description"
"description_teaser"
"code"
An internal event identifier
"disabled": {
"audio"
"audio_dates"
"captioning"
"captioning_dates"
"other_services"
"other_services_dates"
"other_services_information"
"signed"
"signed_dates"
}
"festival"
The curren full name of the festival to be displayed
"festival_id"
"genre"
"genre_tags"
"images": {
"<hash>": {
"hash"
"orientation"
Enumerated value; either "landscape" or "portrait" or "square"
"type"
Enumerated value; either "thumb" or "hero"
"versions": {
Multiple resizes of each image are available, see event image docs
"original": {
"height"
"mime"
"type"
"url"
Prior to 2024 was a scheme-relative URL
"width"
}
}
}
}
"latitude"
"longitude"
"non_english"
"performances": [
{
"type"
"price_type"
"is_at_fixed_time"
Boolean false indicates event is drop-in between start and end time
"price"
"concession"
"price_string"
"start"
"end"
"duration_minutes"
"title"
}
]
"performance_space": {
"name"
"age_limit"
"age_limited"
"capacity"
"wheelchair_access"
}
"performers_number"
"sub_title"
"status"
"title"
"url"
The only unique ID for this event you should use
"updated"
"venue": {
"address"
"code"
"description"
"disabled_description"
"email"
"name"
"phone"
"position": {
"lat"
"lon"
}
"post_code"
"web_address"
}
"warnings"
"website"
The URL to the festival's website for this specific event

Heads up! Future improvements to the API will be backwards compatible with these response formats, but may add additional fields. You should only process API responses with a suitable parser library - attempting to use regular expressions or text libraries may cause your application to break in future.

The following properties will also be present but are no longer populated, they may still contain data for older listings:

{
"categories": {
"strand_titles"
"subjects"
"keywords"
}
"discounts": {
"friends"
"group"
"passport"
"schools"
"two_for_one"
}
"fringe_first"
"performances": [
{
"concession_additional"
"concession_family"
}
]
"sub_venue"
"venue": {
"box_office_fringe"
"box_office_opening"
"cafe_description"
"fax"
"has_bar"
"has_booking_over_card"
"has_booking_over_phone"
"has_booking_over_web"
"has_cafe"
}
"twitter"
}