Stockholm Film Festival API for developers

Register

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:

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:

  1. Include a variable in the URL /v1/festivals/list/API-Key/[your key goes here]/
  2. 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:

What time is it?

All timestamps returned from this API are Unix timestamps. In a few places both nicely formatted dates (2014-09-16) 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/1410828695 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: 2014-09-16. 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: 2014-09-16. 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/1410828695 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/1410828695 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:

Images

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

Poster image formats

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.