Just fill in this form and we will send you an API-key as fast as the electrons can carry the e-mail. Most fields are optional, but the more we know the better we can support you.
Welcome to Stockholm Film Festivals API for developers. The API is a way for your application to access information on all parts of the festival - films, events, venues and more.
To get started all you have to do is to apply for a developer key on this page. They are delivered instantly and for free!
Before you get started here are few pointers:
Information is retrieved by calling a specially constructed URL. For example:
http://api.stockholmfilmfestival.se/v1/festivals/list
All available URLs are listed further down on this page. In this documentation we will list all URLs relative to the server root.
You can include the API-key in your request in two ways:
/v1/festivals/list/API-Key/[your key goes here]/X-API-KEYIf you do nothing the data will be returned as XML-files. By appending a parameter you can get a variety of formats. For example to get a json-formatted response you use:
/v1/festivals/list/format/json/
The formats supported are:
xml – almost any programming language can read XMLjson – useful for JavaScriptcsv – open with spreadsheet programshtml – a simple HTML tablephp – Representation of PHP code that can be eval()’edserialize – Serialized data that can be unserialized in PHPAll timestamps returned from this API are Unix timestamps. In a few places both nicely formatted dates (2012-05-18) and Unix timestamps are returned side by side. Note that the nicely formatted dates are already in Stockholm local time whereas the timestamps are UTC. When timestamps are converted to formatted dates they are converted according to the timezone of the system doing the conversion.
Since all events are being held in Stockholm (after all it's called The Stockholm Film Festival) it's important that you know which time zone your app is using for conversion from timestamps. Make sure when converting from timestamps for events that you are in fact converting to "Europe/Stockholm". Otherwise your app might indicate a starting time for the event that is not at all relevant.
Also note that some timestamps are really just an indication of the relevant date. For example the start date of festivals are just accurate to the day, but the date that ticket sales starts are correct to the second as are the start time of events.
OAuth 2.0 is an emerging standard for providing user authentication between an authentication provider and an external application. The point of OAuth is to allow your app to access the users resources on our server without knowing their user credentials on our site. Users of OAuth 2.0 include Facebook and 37 signals. A list of client implementations can be found on oauth.net.
The OAuth flow is totally independent from the rest of the API. The only time they interact is when you use an access token to retrieve protected resources for a user.
The steps for your app to be able to access a users protected resources are as follows:
Be aware that the token endpoint only returns answers in JSON-format as per the current OAuth2.0 draft.
Our authorization endpoint allows the user to log in (if not already logged in) and authorize your app to use his/her data. The endpoint is located at
https://www.stockholmfilmfestival.se/oauth/authorize/ [Swedish]
https://www.stockholmfilmfestival.se/en/oauth/authorize/ [English]
Note the use of SSL. If you direct your user here with a regular http-request a redirection to a secure channel will occur that causes the GET-parameters to be lost and the authorization to fail. To make the request complete you need to include your API-key as the parameter client_id, the parameter response_type set to code and the parameter redirect_uri that specifies where the user should be sent after authorization. So the complete URL would look something like this:
https://www.stockholmfilmfestival.se/oauth/authorize/?client_id=[your key goes here]&response_type=code&redirect_uri=http%3A%2F%2Fwww.example.com%2Foauthreturn.html
Note that the redirect_uri parameter is URL encoded. You can also pass the optional parameter state which will be preserved and returned to your redirect_uri.
When the user has approved your app to use his/her protected resources they are redirected back to the URL that you specify in redirect_uri with a GET-parameter called code that contains an authorization code. This code is valid for only two minutes so you need to complete step three before it expires. If you specify the optional state parameter this will also be included as a GET-parameter. So in the example above the user would get redirected to
http://www.example.com/oauthreturn.html?code=hQXhYq9XnMnzdrrYpSZAZMd77BYLwJ5R
To obtain an access token that can be used to access user data on api.stockholmfilmfestival.se you make a https POST-request to our token endpoint including the following parameters:
client_id - your API-keyclient_secret - your API-password (it was in the mail)grant_type - authorization_coderedirect_uri - the redirect_uri passed to the authorization endpoint when obtaining the authorization codecode - the authorization code returned to your redirect_uri as a GET-parameterMake your POST-request to the token endpoint https://www.stockholmfilmfestival.se/oauth/token/
A typical response to a sucessful token request will look something like this
{"access_token":"8W4YE38fOubprqYk2FU3A0LXZ1ALcA2a","expires_in":7200,"scope":null,"refresh_token":"r9P6BVDXPTvo7xmT8olc6oomBk0VoN3T"}
The access token is valid for two hours. The refresh token however is valid for five years. Every time you use the refresh token to obtain a new access token you will be issued a new refresh token and the old one will be invalidated. Make sure to update the user entry in your app accordingly.
myfestival among other functions in the API allow you to retrieve/modify user data in our databases. See each entry for specific instructions.
When the access token expires you retrieve a new one by calling our token endpoint with the refresh token. Make a https POST-request to our token endpoint including the following parameters:
client_id - your API-keyclient_secret - your API-password (it was in the mail)grant_type - refresh_tokenrefresh_token - the current refresh token for the userMake your POST-request to the token endpoint https://www.stockholmfilmfestival.se/oauth/token/
The response will look exactly like the the response in step three. Observe that with each request to the token endpoint you will receive a new refresh token and the old one expires!
The events section returns data about events. An event can be both a screening of a film as well as a party or a seminar. Our database contains event data from 2007 onwards since that is when the current database was taken into use.
Since all events display the availability of tickets make sure to check back quite regularly so that your users don't try to purchase tickets to an event that is actually sold out. We recommend at least hourly updates, but every 15 minutes is even better.
Returns a list of events for a given festival. Please note that a single festival consists of several hundred events. If possible use the since-parameter to limit the size of your results. Variables returned:
This function supports adding the parameter since/1337302450 to retrieve events modified after the given Unix timestamp.
Returns a list of events for a given day expressed as a ISO-date: 2012-05-18. Variables returned:
Returns a list of events for a venue combined with a date or festivalId. The day should be expressed as a ISO-date: 2012-05-18. Variables returned:
You can pass both date and festivalId to this function, but if you pass a date outside the given festival no events will be returned. Quite logical, ey?
Returns the full details for the event indicated by eventId. Variables returned:
Returns a list of events that have been changed from the original program for the given festival. Variables returned:
The festival section returns data about festivals
Returns a list of festivals. Variables returned:
Returns data on the festival specified by festivalId. Variables returned:
The film section returns data about films
Returns a list of films for the festival indicated by festivalId. Variables returned:
This function supports adding the parameter since/1337302450 to retrieve films modified after the given Unix timestamp.
Returns a list of films for the festival and section indicated by festivalId and sectionId respectively. Variables returned:
This function supports adding the parameter since/1337302450 to retrieve films modified after the given Unix timestamp.
Returns the full details for the film indicated by filmId. Variables returned:
The section section returns data about sections. A section is a theme for a collection of films screened during the festival.
Returns a list of sections in the festival indicated by festivalId. Variables returned:
The venues section returns data about venues. Not all venues are used during all festivals
Returns a list of venues. Variables returned:
The myfestival section allows your application to edit a users myfestival festival planner. You can try out myfestival here http://www.stockholmfilmfestival.se/myfestival/.
All functions that alter data require a POST-request with the variables specified for each function.
Returns a list of all the users events present in myfestival for the given festivalId. Variables returned:
This function adds the given event to a users myfestival. Requires a POST-request. Variables required:
event_id - the eventId of the event that the user wishes to addtoken - the accessToken the your application has obtained from our token endpointReturn statuses:
success - The event was successfully added to the users myfestivalwarning - The event was not added to the users myfestival, most likely because it was already thereerror - The event was not added to the users myfestival. This can be due to expired access token, wrong token, non existent eventId or some other error.This function removes the given event from a users myfestival. Requires a POST-request. Variables required:
event_id - the eventId of the event that the user wishes to removetoken - the accessToken the your application has obtained from our token endpointReturn statuses:
success - The event was successfully removed from the users myfestivalwarning - The event was not removed from the users myfestival, most likely because it didn't exist in the users list of eventserror - The event was not removed from the users myfestival. This can be due to expired access token, wrong token, non existent eventId or some other error.This function changes haveTicket-status for the given event in a users myfestival. Requires a POST-request. Variables required:
event_id - the eventId of the event that the user wishes to removehave_ticket - the myfestivalHaveTicket-status to be set. Can be true or falsetoken - the accessToken the your application has obtained from our token endpointReturn statuses:
success - The haveTicket-status was successfully changed in the users myfestivalwarning - The haveTicket-status was not changed in the users myfestival, most likely because it already had the same statuserror - The haveTicket-status was not changed in the users myfestival. This can be due to expired access token, wrong token, non existent eventId or some other error.The tickets section allows your application to access the tickets and memberships of a user.
Returns a list of all the tickets stored on the specified card. The card number does not need to be registered to the user identified by the access token. Variables returned:
Returns a list of all the tickets stored on the newest membership card registered to the user identified by the access token. Variables returned:
Returns a list of all the membership cards registered to the user identified by the access token. Variables returned:
To make your application more lively you are welcome to use our images in the design of your application.
We provide two different images for each film; one preview image (generally a still image from the film) and a film poster. Both image types does not exist for all films, but our image cache will always return an image in the given size that can be displayed in your application.
50x28100x56200x113320x180600x338640x3601024x57650x71100x143200x286320x457600x857640x914In the information for a film the API will return two complete URL:s where images can be retrieved. However you will have to replace [IMAGESIZE] in the URL with the image size above that you want to fetch. So just turn:
http://www.stockholmfilmfestival.se/imagecache/[IMAGESIZE]/fileadmin/images/film_images/2008/9_99.jpg
into:
http://www.stockholmfilmfestival.se/imagecache/600x338/fileadmin/images/film_images/2008/9_99.jpg
and you can access the image with any http enabled application.
There is no technical limitation on fetching preview images in poster formats and vice versa, but from an aesthetic perspective we would really advice against this.
Note that these image sizes are pre configured and that arbitrary sizes can not be input. Should your application require different image sizes you can either process the image further in your application or contact us and we will consider adding additional presets.
If you decide to cache images in your application please remember that our images are frequently updated so please check back now and then and make sure to cache a fresh copy.
available/few/soldout. The ticket status is not removed even though the event has passed.59.333618.0598This documentation was last updated 2010-11-04.