Venues API

Endpoint

The API service is exposed at: 

https://api.edinburghfestivalcity.com/venues
/venues filterable list of venues

Query parameters

You can filter the list of venues 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
code Number 123 is venue 123 from Fringe list. Not relevant for non-Fringe venues
year Festival year, for example 2015, or * for all years. The default is the current festival year - which rolls over on the 15th January each year to accommodate the Edinburgh's Hogmanay programme.
post_code Venue postcode, exact string match
Full text search on name
name Any venue matching query
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 Venues where any of the data fields have changed since the specified Europe/London time. There may be a delay of a few minutes between a venue 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 venues 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 `not-in-use` venues.
Paging
size 25 results per response, default is 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

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

{
"id"
The only unique ID for this venue you should use
"name"
The venue name, eg. Assembly George Square Gardens
"festival"
The full name of the festival to be displayed
"festival_id"
"year"
"code"
An internal venue identifier - you should use `id`
"website"
"address"
"post_code"
"position": {
"lat"
"lon"
}
"phone"
"email"
"description"
"access_description"
"performance_spaces": [
{
"name"
"capacity"
"wheelchair_access"
"age_limited"
"age_limit"
Description of age limit / requirements. eg: All bars 18+ for non-ticket holders after 10pm.
}
]
"event_count"
The number of unique events in this venue
"performance_count"
The total number of performances in this venue
"status"
Either `in-use`, `not-in-use`, `deleted`
"updated"
}

Matching and merging venues

Venues in the Festivals API are distinct by festival and by year. This means that the "same" physical venue may be present in the API multiple times with different IDs.

You should never assume that two venue entities with the same name (or same address / geocode) can be treated as a single venue. There are often important differences between the details and characteristics of a venue when used for different festivals or different years. This can include:

  • Physical address and geocode (different festivals may use different primary entrances to the venue / site).
  • Contact details (the site may be operated by a different organisation).
  • Accessibility characteristics.
  • Age restrictions.
  • The way the venue is divided into performance spaces.

However, there are some cases where it may be appropriate to group/merge venues - for example for more established year-round venues. If you wish to do this, you should have a manual process to review potential groupings and confirm that they have equivalent details.