Events API
Overview
Endpoint
There are two resources exposed at:
https://api.edinburghfestivalcity.com/events
/events |
filterable list of events |
/events/{UUID} |
specific event by `UUID` (unique event identifier) |
Query parameters
You can filter the list of events with any or all of the following optional parameters.
Basic search | |
---|---|
festival |
Festival ID, possible values are fringe, demofringe, jazz, book, international, tattoo, art, hogmanay, science, imaginate, film, mela, storytelling |
genre |
Available genres vary by festival and year - explore the data to see the range of values. |
country |
Country of origin of the company/artist/production - not populated for all events. |
code |
Festival-specific event code - useful for matching against other systems. |
year |
Festival year, for example 2015, or * for all years. Defaults to the current festival year - which rolls over on the 15th January each year to accommodate the Edinburgh's Hogmanay programme. |
Full text search on titles, descriptions and artists | |
title |
Matches individual words or phrase within title |
description |
Matches individual words or phrase within description |
artist |
Matches individual words or phrase within artist name - Not populated for all events. |
Date search | |
date_from |
Events with performances after the specified Europe/London time. |
date_to |
Events with performances before the specified Europe/London time. |
Price search | |
price_from |
Events with at least one performance where minimum full price is more than {{value}} |
price_to |
Events with at least one performance where minimum full price is less than {{value}} |
Accessibility options | |
has_audio_description=1 |
Events where at least one performance has audio description available. Relevant performance dates are included in audio_dates |
has_captioning=1 |
Events where at least one performance has captioning available. Relevant performance dates are included in captioning_dates |
has_signed=1 |
Events where at least one performance is signed. Relevant performance dates are included in signed_dates |
has_other_accessibility=1 |
Events where at least one performance where other accessible options are available. These typically include relaxed performances and touch tours. Details are given in other_services_information |
Venue search | |
venue_name |
Any venue matching query |
venue_code |
Number (123, 456) is venue ID from Fringe list. Not relevant for non-Fringe venues |
post_code |
Venue postcode, exact string match |
Geographic location by distance from latitude / longitude | |
lat |
Latitude |
lon |
Longitude |
distance |
Circle around Lat/Lon point. Specified as Xmiles or Xkilometers (note no space, eg. 10miles or 1kilometers) |
Last modified search | |
modified_from |
Events where any of the data fields have changed since the specified Europe/London time. There may be a delay of a few minutes between an event being marked as modified and it being returned in an API query. Therefore, if you are using this query to synchronise a local copy of the data you should add a ten minute window to ensure you receive all changes. For example, if you sent your last query at 10:00:00 you should pass a modified_from of 09:50:00 with your next query. This may result in a few events being received in both updates and you should handle this appropriately in your application. Including this parameter will trigger the API to include deleted and cancelled events. See the section on event status for further details. |
Pagination | |
size |
Number of results per response, defaults to 25, max value is 100 |
from |
Index of the first result to return - for example, with size=25 you would query with from=0, from=25, from=50, etc. |
Other options | |
pretty |
Adding &pretty=1 to your search query will make any format human readable |
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.
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:
Event Status
Events should only be matched or changes tracked based on the unique url
key in the response.
It
is
essential that you do not attempt to match similar looking events on their titles, venues
etc
as
these are likely or known to change.
By default, API responses do not include events that have been removed from the original festival's listings or where they are explicitly marked as cancelled in the data we receive. For most API queries, you should consider all events received as being active and display them accordingly.
However, if you include a modified_from parameter in your search
query, the API may also return inactive events. This is to ensure you can consistently update any
local cached or stored versions of the data when events are deleted or cancelled. The JSON
formats include a status
field for each event which should be interpreted as follows:
status |
Expected action |
---|---|
empty/missing | Event is active - display as normal |
active |
Event is active - display as normal |
cancelled |
Event has been cancelled. You may continue to display the event, or remove it, as appropriate to your application. |
deleted |
Event has been removed from the API database. This may be because it was cancelled and the festival source data does not provide an explicit cancelled event status. Or it may have been added to the API in error and subsequently deleted. You must remove this event from any local database and stop displaying it in your application. |
As a fallback for backwards compatibility with clients that do not properly handle the status field, the API also amends the title, description and performances list for events that have been deleted or cancelled.