Stockholm Film Festival API for developers
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:
- This is a work in progress. Changes can and will happen.
- We will work hard to not remove information from the API, but the structure of the response might change and information can be added. Parse the data returned based on variable names and not indices. Don't say you weren't warned if your application goes bust because you are using numbered indices for your parsing.
- At the moment we have chosen not to implement quotas. You are sharing database resources directly with our web and ticketing system. Write your app thoughtfully or write your own cache. We reserve the right to de-activate any API-key that consumes unreasonable amounts of resources.
- Our servers sometimes experience heavy loads, especially when the tickets are released. We will work hard to mitigate this for the API, but be warned that clock cycles are in high demand and this will likely affect the responsiveness of the API during these times as well.
- Send your questions and much appreciated feedback to api@stockholmfilmfestival.se
- News about the API will be posted via this non-intrusive Twitter-account, follow it! http://twitter.com/sffapi
Enough of boring reservations. Let's get started!
Table of contents
Basic usage
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.
Include API-key
You can include the API-key in your request in two ways:
- Include a variable in the URL
/v1/festivals/list/API-Key/[your key goes here]/
- Include it in the HTTP-header of your request under the name
X-API-KEY
Choose response format
If 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 PHP
What time is it?
All timestamps returned from this API are Unix timestamps. In a few places both nicely formatted dates (2013-05-20) 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.
Events
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.
/v1/events/festival_list/festival_id/[festivalId]/
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/1369037643 to retrieve events modified after the given Unix timestamp.
/v1/events/date_list/date/[date]/
Returns a list of events for a given day expressed as a ISO-date: 2013-05-20. Variables returned:
/v1/events/venue_list/venue_id/[venueId]/date/[date]/
/v1/events/venue_list/venue_id/[venueId]/festival_id/[festivalId]/
Returns a list of events for a venue combined with a date or festivalId. The day should be expressed as a ISO-date: 2013-05-20. 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?
/v1/events/event/event_id/[eventId]/
Returns the full details for the event indicated by eventId. Variables returned:
/v1/events/change_list/festival_id/[festivalId]/
Returns a list of events that have been changed from the original program for the given festival. Variables returned:
Festivals
The festival section returns data about festivals
/v1/festivals/list/
Returns a list of festivals. Variables returned:
/v1/festivals/festival/festival_id/[festivalId]/
Returns data on the festival specified by festivalId. Variables returned:
Films
The film section returns data about films
/v1/films/festival_list/festival_id/[festivalId]/
Returns a list of films for the festival indicated by festivalId. Variables returned:
This function supports adding the parameter since/1369037643 to retrieve films modified after the given Unix timestamp.
/v1/films/section_list/festival_id/[festivalId]/section_id/[sectionId]/
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/1369037643 to retrieve films modified after the given Unix timestamp.
/v1/films/film/film_id/[filmId]/
Returns the full details for the film indicated by filmId. Variables returned:
Sections
The section section returns data about sections. A section is a theme for a collection of films screened during the festival.
/v1/sections/list/festival_id/[festivalId]/
Returns a list of sections in the festival indicated by festivalId. Variables returned:
Venues
The venues section returns data about venues. Not all venues are used during all festivals
/v1/venues/list/
Returns a list of venues. 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.
Preview image formats
50x28100x56200x113320x180600x338640x3601024x576
Poster image formats
50x71100x143200x286320x457600x857640x914
In 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/sites/default/files/styles/[IMAGESIZE]/public/film_images/2011/oslo_31_augusti.jpg
into:
http://www.stockholmfilmfestival.se/sites/default/files/styles/640x914/public/film_images/2011/oslo_31_augusti.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.
Variable list
Events
- eventId
- The unique numeric id assigned to each event. Never display this id to the user, use eventNumber instead.
- eventNumber
- The public event number communicated to the user in our filmprogram. Note that these numbers are not unique!
- eventName_sv
- The name of the event in Swedish
- eventName_en
- The name of the event in English
- eventDate
- The ISO-date of the event
- eventTime
- The start time of the event
- eventTimestamp
- The start time of the event as a Unix timestamp
- eventHasFaceToFace
- A boolean indicating whether the event includes a Face2Face discussion with one of the guests of the festival. If so additional data can be found by looking up the specific event.
- eventLength
- The length of the event in minutes. This may differ significantly from the film length because it my also include a short film and extra time for interviews and other additional happenings.
- eventStatus_sv
- When an event is changed, for example a change in starting time or film shown, eventStatus_sv contains an explanation in Swedish of the nature of the changes.
- eventStatus_en
- When an event is changed, for example a change in starting time or film shown, eventStatus_en contains an explanation in English of the nature of the changes.
- eventTicketStatus
- The ticket status for the event. Can be one of three statuses
available/few/soldout. The ticket status is not removed even though the event has passed.
- eventBuyURL
- A URL to place a ticket to the event in the shopping cart on the filmfestival website. The URL is removed 15 minutes after the event starts or when the event is sold out. Please use the existence of this URL to determine whether your app should display a "Buy"-button or not.
- eventBuyOneTimeURL
- A URL to place a one time ticket to the event in the shopping cart on the filmfestival website. One time tickets are our tickets for visitors who are curious about the festival and want to buy tickets to few showings without the need for a membership card. The URL is removed 15 minutes after the event starts or when the event is sold out. Please use the existence of this URL to determine whether your app should display a "Buy"-button or not. (DEPRICATED, this now returns the same as eventBuyURL)
- eventModifiedTimestamp
- A Unix timestamp indicating when the event was last modified
- shortFilmId
- The filmId of the short film shown before the main feature. This id can be used to look up further information about the film.
- shortFilmName_sv
- The name of the short film in Swedish
- shortFilmName_en
- The name of the short film in English
- faceGuest
- The name of the guest of any Face2Face in connection to the event
- faceModerator
- The name of the moderator of any Face2Face in connection to the event
- faceDescription_sv
- The description in Swedish of any Face2Face in connection to the event
- faceDescription_en
- The description in English of any Face2Face in connection to the event
Festivals
- festivalId
- The numeric id assigned to each festival. Observe that festivals are not numbered in a running sequence!
- festivalName
- The name of the festival
- festivalBegin
- The start date of the festival
- festivalEnd
- The end date of the festival
- festivalProgramReleaseTimestamp
- The time when the program for the festival is published
- festivalTicketReleaseTimestamp
- The time when the tickets for the festival are released
- festivalIsCurrent
- If true this is the current festival. The switchover occurs every year when the program for the upcoming festival is released.
Films
- filmId
- The numeric id assigned to every film
- filmName
- The name of the film.
- filmName_en
- The english name of the film.
- filmPreviewImage
- The filename of the preview image for the film. For more information on how to access the images please see the section on Images
- filmPosterImage
- The filename of the poster image for the film. For more information on how to access the images please see the section on Images
- filmOriginalLanguageName
- The name of the film in its original language
- filmOfficialHomesite
- The URL to the official web site for the film
- filmDirector
- The name of the films director(s)
- filmProducer
- The name of the films producer(s)
- filmProductionYear
- The year the film was produced
- filmLength
- The running time of the film in minutes. Please observe that the total length of an event often differs from the films running time!
- filmIMDBId
- The id of the film at www.imdb.com
- filmDescription_sv
- The description of the film in Swedish
- filmDescription_en
- The description of the film in English
- filmFilename
- The filename used for the film
- filmTrailerLink (depricated! Instead use 'filmYoutubeId')
- The link to the filmtrailer
- filmYoutubeId
- The link to the filmYoutubeId
- filmStatus_sv
- The status of the film in Swedish (World premiere, Nordic premiere etc.)
- filmStatus_en
- The status of the film in English (World premiere, Nordic premiere etc.)
- filmCinematography
- The name of the cinematographer(s) of the film
- filmScript
- The name of the scriptwriter(s) of the film
- filmMusic
- The name of the films composer(s)
- filmCast
- The name(s) of the principal cast of the film
- filmCountry_sv
- The name of production country of the film in Swedish
- filmCountry_en
- The name of production country of the film in English
- filmLanguage
- The language of the film
- filmSubtitle_sv
- The Swedish name of the language the film is subtitled in
- filmSubtitle_en
- The English name of the language the film is subtitled in
- filmProductionCompany
- The name of the films production company
- filmInternationalRights
- The name of the company holding the international film rights of the film
- filmSwedishDistribution
- The name of the films Swedish distribution company
- filmMobileTrailer
- The URL to the mobile trailer for the film
- filmMobileDownloadTrailer
- The URL to the file for download to mobile phones
- filmIphoneTrailer
- The URL to the iPhone trailer for the film
- filmInfoURL
- The URL to the information page for the film on the Stockholm Film Festival website
- filmModifiedTimestamp
- The Unix timestamp of the last modification of this film
- filmFestivalOnDemand
- True if the film is included in the campaign "Festival on Demand"
Sections
- sectionId
- The numeric id assigned to every section
- sectionName
- The name of the section
- sectionDescription_sv
- A desription of the section in Swedish
- sectionDescription_en
- A desription of the section in English
Venues
- venueId
- The numeric id assigned to every venue
- venueName
- The name of venue
- venueCinema
- The name of the cinema where this venue is located
- venueAddress
- The street address of the venue
- venueType_sv
- The type of venue in Swedish. Biograf, bar, klubb, affär, etc.
- venueType_en
- The type of venue in English. Cinema, bar, club, shop, etc.
- venueLat
- The latitude of the venue according to WGS84 as a decimal value, for example
59.3336
- venueLon
- The longitude of the venue according to WGS84 as a decimal value, for example
18.0598
- venueDescURL
- A link to the information page about the cinema on the filmfestival website
This documentation was last updated 2012-08-06.
