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

Table of contents

• Basic usage
• Events
• Festivals
• Films
• Sections
• Venues
• Images
• Variable list

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:

• xml – almost any programming language can read XML
• json – useful for JavaScript
• csv – open with spreadsheet programs
• html – a simple HTML table
• php – Representation of PHP code that can be eval()’ed
• serialize – 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 (2015-03-03) 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.

Festivals

The festival section returns data about festivals

Films

The film section returns data about films

Sections

The section section returns data about sections. A section is a theme for a collection of films screened during the festival.

Venues

The venues section returns data about venues. Not all venues are used during all festivals

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

• 50x28
• 100x56
• 200x113
• 320x180
• 600x338
• 640x360
• 1024x576

Poster image formats

• 50x71
• 100x143
• 200x286
• 320x457
• 600x857
• 640x914

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. (DEPRECATED, 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 (deprecated!)

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 (deprecated! 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 (deprecated! Instead use 'filmYoutubeId')

The URL to the mobile trailer for the film

filmMobileDownloadTrailer (deprecated! Instead use 'filmYoutubeId')

The URL to the file for download to mobile phones

filmIphoneTrailer (deprecated! Instead use 'filmYoutubeId')

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 (deprecated!)

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.