Querying the API
Overview
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
URL encoding in queries You should calculate the signature after URL-encoding any parameters. For example, to search for the
title "Mrs Brown" you would first build the URL /events?title=Mrs%20Brown&key=12345
and then sign
this string and append the signature.
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.