Querying the API

Querying the API

URL endpoints

The API service currently exposes 2 resources at:

https://api.edinburghfestivalcity.com

/events filterable list of events
/events/{UUID} specific event by `UUID` (unique event identifier)

Available 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. The default is 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 performers
title Strict matching against the event title
description Matches event description - query types as above
artist Matches artist name - query types as above. 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.
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

Authentication

An access key is required for all requests to the API and can be created from your profile. You must not reuse an access key between projects - you can create as a many access keys as you require.

Your secret token is used to calculate the correct signature for each API request and must never be disclosed as it is used to verify your requests.

The signature is calculated using the HMAC-SHA1 algorithm:

  • Build the full API request URL, including your access key but excluding the server domain - eg /events?festival=book&key=12345. See the note below on URL encoding.
  • Calculate the HMAC hash of the URL using the SHA1 algorithm using your secret token as the key.
  • Append the hex-encoded hash to your URL as the signature parameter

Signature encoding

Some languages - notably C# - default to encoding hashes in UTF-16. Ensure your signature is encoded in plain ASCII hex or it will not be valid.

Signature examples

$api_key    = '12345678';
$secret_key = '135fa25acs33';
$query      = '/events?filter=that&key='.$api_key;
$signature  = hash_hmac('sha1', $query, $secret_key);
$url        = 'https://api.edinburghfestivalcity.com'.$query.'&signature='.$signature;

// HINT:
// you can use our official PHP client to take care of all this for you
//     https://github.com/festivalslab/api-client-php
//
// it's also available on composer
//    composer require festivalslab/api-client-php
import hmac
import hashlib
api_key     = '12345678'
secret_key  = '135fa25acs33'
query       = '/events?filter=that&key=' + api_key
signature   = hmac.new(secret_key, query, hashlib.sha1).hexdigest()
url         = 'https://api.edinburghfestivalcity.com' + query + '&signature=' + signature

Valid request URL:

https://api.edinburghfestivalcity.com/events?festival=jazz&key=12345678&signature=e471178c45d33d7a37f99f74f8ff59d97749e7bf

Access to Fringe listings

To access live Edinburgh Festival Fringe data you will need to apply for approval. All users can access a set of randomised Fringe data for testing, which you can request by including the festival=demofringe parameter in your search terms. All users have access to live listings data for events from the other participating festivals.

Synchronising with a local database

If you're using the API to feed a high-traffic site, or to merge with data from other sources, you may want to keep a local copy of our data. All the festival listings change over time, so you'll need to regularly synchronise this to keep it up to date. You're required to do this at least once every 24 hours, but we recommend more often if you can.

Each event has a url field that is guaranteed to be unique and constant even if the event's title / date / etc changes. This field is the event's ID in the API : we strongly recommend storing this and using it to match up data between each import.

To fetch just the updated events, use the modified_from query parameter with a time ten minutes before your last request. For example: ?modified_from=2017-02-13+09:50:00. Note that this query will also return cancelled and deleted events : see the event status documentation.

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.