International Showtimes API

Version: 5

Base URI: https://api.internationalshowtimes.com/v5

Introduction

Welcome

Welcome to the Documentation for the International Showtimes API. We include movie metadata, showtimes data, ticket deep linking in one simple API for your online or offline content, apps or services. We are delivering best data for Europe, USA, Oceania, Asia Pacific, South America and other planets you might be looking for.

Support

Please raise any questions or report issues regarding the API via our JIRA Service Desk System.

Authentication

An apikey must be sent with every request. To get your API-Key sign up for a free trial.

There are multiple options to send the apikey:

HTTP Authentication: Token Access Authentication
- Example: curl "https://api.internationalshowtimes.com/v5/cinemas/" -H "Authorization: Token token=YOUR_API_KEY"
HTTP Header 'X-API-Key'
- Example: curl "https://api.internationalshowtimes.com/v5/cinemas/" -H "X-Api-Key: YOUR_API_KEY"
URL parameter
- Example: curl "https://api.internationalshowtimes.com/v5/cinemas/?apikey=YOUR_API_KEY"

Please avoid sending the apikey via URL parameter if possible. Use one of the HTTP Headers options instead!

Example Requests

The following examples demonstrate the usage of basic query parameters for some use simple cases. Most of the available parameters work like filters and be combined according to your needs. Values in curly braces are placeholder.

Get all cinemas in a specific country

GET https://api.internationalshowtimes.com/v5/cinemas/?countries=DE

Get all cinemas at a specific coordinate within a distance of 30 kilometres.

GET https://api.internationalshowtimes.com/v5/cinemas/?location=52.5,13.37&distance=30

How to get all movies playing in a particular cinema

GET https://api.internationalshowtimes.com/v5/movies/?cinema_id={ID}

Search for a movie by german title

GET https://api.internationalshowtimes.com/v5/movies?search_query=Avengers&search_field=title&lang=de

Get a list of upcoming movies for Germany

GET https://api.internationalshowtimes.com/v5/movies?include_upcomings=true&countries=DE&release_date_from={DATE}

release_date_from should be set to a date slightly in the future to exclude current movies, for example tomorrow or today + 1 week.

Fetch only a subset of available fields for a particular movie

GET https://api.internationalshowtimes.com/v5/movies/30767?fields=id,title,original_title,release_dates,imdb_id

Get all showtimes of a movie playing in all theatres within a radius of 30 kilometres around a certain coordinate

GET https://api.internationalshowtimes.com/v5/showtimes?movie_id=18047&location=52.331705,13.37&distance=30

Get all showtimes per movie in a specific City

GET https://api.internationalshowtimes.com/v5/showtimes?city_ids=1&movie_id=12345

Localization

Movie metadata is available in different languages and locales. To specify the locale for retrieving movie metadata include a supported locale via one of the following ways. The locale can be specified for any requests which include movie data (such as the movies or the showtimes endpoints).

URL parameter `lang`

Example: curl "https://api.internationalshowtimes.com/v5/movies/?lang=de"

HTTP Header `Accept-Language`

Any valid value as specified in RFC2616 will be handled.

Example: curl "https://api.internationalshowtimes.com/v5/movies/" -H "Accept-Language: de"

Fetch the Locale - index endpoint to see which locales are available.

Miscellaneous

Identifiers

All identifiers are of type string even if they could actually also be integer. The reason for that is simply the role of these values being nothing but identifiers. This means even if the strings are serial numbers or any other logic, there is no guarantee it will stay the same. Hence, building anything based on any identifier structure may break in the future.

JSON Keys

When comes to naming JSON keys there are many debates about CamelCase vs underscores. Considering JSON actually standing for JavaScript Object Notation means it should be CamelCase - as that's native to JavaScript, we think underscores have a better readability.

API Updates

As of mid 2019 the API has been updated with a new major version. Click over here if you need to access the documentation for the previous version.

2024-11-13:

New

Showtimes endpoint
- Added a new field movie_page_link to the response of the Showtimes endpoint. This field can be used as an alternative if a deeplink is not provided in the response

2023-12-14:

New

Movies endpoint
- Added a new field age_limits_descriptors that contains the descriptors information with age rating for Germany (DE). Information is provided in English (en) and German (de) translations. It is different information that is visible in age_limits
- Example: "age_limits_descriptors": {"DE": {"age": "12", "descriptors": [{"en": "violence", "de": "Gewalt"}]}}

2023-01-18:

New

Showtimes endpoint
- Added new filter for attribute_codes property to retrieve showtimes

2021-01-14:

New

Showtimes endpoint
- Added changed_since query parameter, that allows to fetch incremental showtimes updates.

2019-05-05: V4 → V5

New

new Attribute endpoint

Model Updates

Country Model Updates

change	description
new	`continent` property

Showtimes Model Updates

change	description
new	`attribute_codes` property
removed	`is_3d` is now covered via of new `attributes` property
removed	`is_imax` is now covered via of new `attributes` property

FAQS

What are the best practices to implement your Cinema Showtimes API?

Regarding the implementation process, each API user has its unique approach when it comes to utilizing our API. In most cases, the users tend to retrieve data for the entire market, store it locally, and then develop their own functionalities on top of it.

How many API calls can I make in a specific timeframe?

The distinction in question pertains to whether your utilization involves our shared server infrastructure or a dedicated server arrangement. Furthermore, it's noteworthy that the performance attributes of a dedicated server are contingent upon its particular configuration. To illustrate, an illustrative instance of a dedicated server showcases a request potential of up to 20,000 requests per hour. Importantly, we wish to emphasize that, at present, there are no explicit constraints imposed on the quantity of API calls you may make.

How can I understand the 200 and 301 response upon reloading or subsequent API queries?

Our application utilizes a Load Balancer to distribute incoming network traffic across multiple servers for optimal performance and reliability. The HTTP 301 status code you're experiencing indicates this redirection process, designed to maintain service performance. We suggest using a library that automatically follows HTTP redirects or implementing a solution where your application retries requests until a non-301 response is received.

Why do we receive showtimes data from the day before?

Our API covers a diverse range of countries, each operating in different time zones. This necessitates the consideration of various time differences when it comes to showtimes. To ensure that our users have accurate and up-to-date information, we maintain old showtimes on our API for up to 24 hours before they eventually disappear. This approach allows us to accommodate the varying timeframes in which showtimes might be relevant across different regions.

How can I understand if a cinema removed showtimes?

It's important to note that our dataset undergoes updates several times daily. When cinemas modify their schedules, we conduct reimports of the showtimes data. During this process, if a showtime has already passed or has been deleted by the cinema, it naturally ceases to be visible within our API. Consequently, there is no requirement for us to implement specific markers on our end for such instances, as they are inherently excluded from our dataset.

How can I query showtimes through a daily bulk export, with the potential inclusion of incremental updates (deltas)?

In our API implementation, we have integrated HTTP-Caching mechanisms which can be found here
https://api.internationalshowtimes.com/documentation/v5/#HTTP-Caching--advanced-
When you make a request to our API, it will provide a complete response if there have been any changes in the API data since your last request. If there have been no alterations in the data, the API will respond with an empty response body accompanied by the status code 304 (Not Modified).

How can I query all showtimes for a specific city?

First, obtain a list of cities available in a country with this API request:
https://api.internationalshowtimes.com/v5/cities/?apikey={YOUR_API_KEY}&countries={ADD_COUNTRY_ISO_CODE}
Once you have the city's unique identifier (ID), retrieve the showtimes for that city using this example API request:
https://api.internationalshowtimes.com/v5/showtimes/?city_ids={ADD_CITY_ID}&apikey={YOUR_API_KEY}&countries={ADD_COUNTRY_ISO_CODE}
These steps allow you to retrieve screening schedules within the specified city.

How can I query showtimes for a movie and user location and then streamline retrieved details for multiple cinemas in one API call?

You can retrieve the required information by using this format:
https://api.internationalshowtimes.com/v5/showtimes?location=39.894543631101804,-86.38220454013391&distance=30&apikey={YOUR_API_KEY}&append=cinemas&movie_id={ADD_MOVIE_ID}
With the 'append' parameter, you specify to include relevant movies and/or cinemas in the response.

How can I utilize the IMDB, TMDB, and Rentrak IDs as filtering criteria for showtimes?

IMDB, TMDB and/or Rentrak ID-s are only used for getting movie details or identifying our internal movie ID, not as a filter for showtimes. For example, to retrieve movies by IMDb_ID, use:
https://api.internationalshowtimes.com/v5/movies?imdb_id=tt10293406&apikey={YOUR_API_KEY}
This request gets movie details based on the provided IMDb_ID. The same logic would count for TMDB (tmdb_id) and Rentrak (rentrak_film_id).

Can we link our standard movie IDs (aligned with TMDB IDs) to ISA movie IDs and send a request parameter containing multiple movie IDs (our internal or TMDB IDs) to the showtimes endpoint?

You can link your internal movie ID with an ISA movie ID by using this request:
https://api.internationalshowtimes.com/v5/movies?tmdb_id={ADD_TMDB_ID}&apikey={YOUR_API_KEY}
For a list of available movies in our API, use:
https://api.internationalshowtimes.com/v5/movies/?apikey={YOUR_API_KEY}&countries={ADD_ISO_CODE}&include_upcomings=true&all_fields=true
However, there's currently no parameter for multiple movie IDs, whether internal or TMDB IDs.

Why is there a redirection to a different cinema ID when retrieving showtimes for a specific cinema?

At International Showtimes, we ensure data accuracy by consolidating duplicate venue entries. If you request showtimes for a cinema ID flagged for removal due to duplication, our system automatically redirects you to the correct and existing cinema ID, maintaining accurate information.

How can I query movies that will be released in the future?

We source our movie metadata from TMDB, ensuring that any movie listed on TMDB can also be retrieved through our API. To include movies in the movies table that do not yet have associated showtimes, you can enable this functionality by adding the parameter 'include_upcomings=true' to your request.
Please note that specifying the relevant countries is necessary. An example of the request format is as follows:
https://api.internationalshowtimes.com/v5/movies/?apikey={YOUR_API_KEY}&countries={COUNTRY_ISO_CODE}&include_upcomings=true
By utilizing this parameter in conjunction with the specified countries, you can access movies without showtimes in the Movies table.

How can I query movie information like plot summaries, cast, director, movie distributor, and ratings from IMDB or Rotten Tomatoes?

We offer an endpoint tailored to provide comprehensive movie metadata for specific films, with the exception of information regarding the movie distributor. You can initiate a request using the following format, as demonstrated here for the movie with ID 30121:
https://api.internationalshowtimes.com/v5/movies/30121?apikey={YOUR_API_KEY}
Through this endpoint, you can access a wealth of information, including details about the movie's runtime, cast, director, synopsis, and TMDB ratings.

How can I filter movies by specific language preferences?

You can filter movie content by language using the 'lang' parameter, but please note that 'scene_images' cannot be filtered by language. For example, you can make the following request:
https://api.internationalshowtimes.com/v4/movies/{ADD_MOVIE_ID}?lang=en&apikey={YOUR_API_KEY}
This allows you to effectively filter movie content to your desired language.

What is the rationale behind certain movies having alphanumeric phrases as slugs, as opposed to having slugs that are more easily comprehensible by humans?

The presence of alphanumeric slugs, particularly in the case of movies with non-English characters or special symbols, is a result of our reliance on TMDB for movie metadata importation. This occurrence may extend to various other films that exhibit similar characteristics.

API Endpoints

Attributes

Movie screenings are held in a variety of differnt experiences by showing different version of the movies (e.g. 3D or IMAX) or adding other features to the event. Each experience added to a showtime is considered an attribute of it.

/attributes get head

get

Retrieve the list of all attributes.

head

Use HEAD requests to query total number / count of a attributes. Allows to apply all filters as available via GET.

Retrieve the list of all attributes.

Response

HTTP status code 200

Body

Type: application/json

Schema:

Attributes Collection Schema

property	type	description
attributes	array of `object`
code	string	The identifier of the attribute used in attributes list on showtimes
title	string	Title for displaying the attribute
description	string	Description explaining the attribute in english language

Example:

{
  "attributes": [
    {
      "code": "3D", 
      "title": "3D", 
      "description": "3D Version"
    }
  ]
}

Locales

Locales are important to control the language of any translatable content, such as movie data or city names.

/locales get head

get

Retrieve the list of all available locales.

head

Use HEAD requests to query total number / count of a locales. Allows to apply all filters as available via GET.

Retrieve the list of all available locales.

Response

HTTP status code 200

Body

Type: application/json

Schema:

property	type	nullable	description
locales	array of `string`		Locale as ISO 639 codes

Example:

{
  "locales": [
    "de",
    "de-CH",
    "en",
    "fr",
    "fr-CH",
    "es",
    "nl",
    "it",
    "da",
    "sv",
    "fi",
    "ru"
  ]
}

Countries

Cinema data, as well as showtime data, is available in many countries. However, access may be only granted to a limited subset for a given API-key. Use this endpoint to see which countries are available in general and to your apikey.

/countries get head

get

Retrieve the list of all countries.

head

Use HEAD requests to query total number / count of a countries. Allows to apply all filters as available via GET.

Retrieve the list of all countries.

Response

HTTP status code 200

Body

Type: application/json

Schema:

Country Collection Schema

property	type	description
countries	array of `object`
iso_code	string	ISO 3166-1 alpha-2 country code
name	string	Localized name of the country
continent	string	The continent of the country (in english, not localized)
is_access_granted	boolean	Indicates if access to data for the country is granted for the given apikey.

Example:

{
  "countries": [
    {
      "iso_code": "DE",
      "is_access_granted": true
    },
    {
      "iso_code": "AT",
      "is_access_granted": true
    },
    {
      "iso_code": "CH",
      "is_access_granted": true
    },
    {
      "iso_code": "GB",
      "is_access_granted": false
    },
    {
      "iso_code": "IE",
      "is_access_granted": false
    },
    {
      "iso_code": "US",
      "is_access_granted": false
    },
    {
      "iso_code": "CA",
      "is_access_granted": false
    }
  ]
}

Cities

The collection of cities.

/cities get head

get

Retrieve the list of all cities, optionally filtered.

head

Use HEAD requests to query total number / count of a cities. Allows to apply all filters as available via GET.

Retrieve the list of all cities, optionally filtered.

Request
Response

Query Parameters

page_token: (string)
Returns the page for the given token based on the initial query. All other parameters will be ignored.
page_size: (integer - default: 100)
Specifies the page size to be used for token based pagination.
Example: 50
offset: (integer)
Skips over a number of elements by specifying an offset value for the query.
Example: 20
limit: (integer - default: unlimited)
Limits the number of elements on the response.
Example: 100
lang: (string)
Specifies the language for the resource's content given as an ISO 639 locale code. See Localization for more.
Example: de
countries: (string)
Filters the cities by country based on a single or a list of ISO 3166-1 alpha-2 codes. Fetch the Countries - index endpoint to see which countries are available.
Example: DE,AT
include_all: (boolean - default: false)
Defines whether to include cities without showtimes.
near_to: (string)
Sorts cities by distance to geo-point. Format: lat,lon.
Example: 50.92695,7.00021
movie_id: (string)
Filter cities to the ones that play the given movie in current week.
query: (string)
Search cities by name in any localization.

HTTP status code 200

Body

Type: application/json

Schema:

City Collection Schema

property	type	nullable	description
meta_info	object		Dictionary of meta data describing the current chunk of the movie list.
cities	array of `object`
id	string
name	string		localized name of the city
slug	string		SEO friendly identifier
lat	number	✓	approximate latitude of the city center
lon	number	✓	approximate longitude of the city center
country	string		ISO 3166-1 alpha-2 country code

Sub Schemas

`meta_info` (object)

property	type	nullable	description
range_from	number		Index of the first item in the current chunk of the list.
range_to	integer		Index of the last item in the current chunk of the list.
total_count	integer		Total number of items in the list.
page_index	integer	✓	Index of the current page. (Is only present when working with token based pagination.)
page_count	integer	✓	Total number of pages. (Is only present when working with token based pagination.)
next_page_token	string	✓	Token to retrieve the next page of the current list. (Is only present when working with token based pagination.)

Example:

{
  "cities": [
    {
      "id": "1",
      "name": "Berlin",
      "slug": "berlin",
      "lat": 52.50735,
      "lon": 13.42855,
      "country": "DE"
    },
    {
      "id": "2",
      "name": "Köln",
      "slug": "koeln",
      "lat": 50.92695,
      "lon": 7.00021,
      "country": "DE"
    },
    {
      "id": "3",
      "name": "Hamburg",
      "slug": "hamburg",
      "lat": 53.5543,
      "lon": 10.0454,
      "country": "DE"
    },
    {
      "id": "4",
      "name": "Frankfurt am Main",
      "slug": "frankfurt-am-main",
      "lat": 50.121212,
      "lon": 8.6365638,
      "country": "DE"
    }
  ]
}

Cinemas

The collection of cinemas.

/cinemas get head

get

Retrieve the list of all cinemas, optionally filtered.

head

Use HEAD requests to query total number / count of a cinemas. Allows to apply all filters as available via GET.

Retrieve the list of all cinemas, optionally filtered.

Request
Response

Query Parameters

search_query: (string)
Filters the cinemas list by the search query. Therefore a regular expression applies to the list where the given string is used as the pattern part of the regex. The regex's options are always set to case insensitivity (/i).
Example: ^Spectre
search_field: (string)
Along with a search_query parameter provide the field to be searched in.
Fields: name, website, zipcode
offset: (integer)
Skips over a number of elements by specifying an offset value for the query.
Example: 20
limit: (integer - default: unlimited)
Limits the number of elements on the response.
Example: 100
city_ids: (string)
Filters the cinemas to those being in the given list of city_ids. Fetch the Cities - index endpoint to seek for cities.
Example: 1,2,3
chain_ids: (string)
Filters the cinemas by the giving single or list of chain ids. Fetch the Cinema Chains - index endpoint to seek for chains.
Example: 1,2,3
location: (string)
Retrieve cinemas in a particular area by passing a geo loaction as center in the format lat,lon.
Example: 52.50,13.37
distance: (number - default: 20 - maximum: 50)
For retrieving cinemas in a particular area along with the location you may want to specify the maximum distance given in kilometers. Results will be sorted by distance in ascending order.
Example: 10
bounds: (string)
Limit cinemas to geographical polygon given as list of at least two points in the following format: (lat,lon),(lat,lon)[,(lat,lon)...]
When passing only two points a bounding box will be built. For polygons make sure there are no crossing edges by sorting the points appropriately.
Example: (52.1,13.15),(52.9,13.37)
countries: (string)
Filters the cinemas by country based on a single or a list of ISO 3166-1 alpha-2 codes. Fetch the Countries - index endpoint to see which countries are available.
Example: DE,AT
time_from: (string - default: beginning of today in UTC timezone)
Filters the list of cinemas to those having showtimes at the given point in time or later.
Hint: Only in combination with movie_id.
Time format: Any parsable date-time string should work, however ISO8601 as in RFC3339 is recommended.
Example: 2016-04-24T00:00:00-08:00
time_to: (string - default: infinity)
Filters the list of cinemas to those having showtimes at the given point in time or earlier.
Hint: Only in combination with movie_id.
Time format: Any parsable date-time string should work, however ISO8601 as in RFC3339 is recommended.
Example: 2016-05-01T00:00:00-08:00
movie_id: (string)
Filter the cinemas to those having showtimes for a selected movie.
Hint: Should be use in combination with time_from and time_to.
fields: (string)
Defines the list of fields for building the shallow list of cinemas. Defaults to including all cinemas fields.
Example: id,name,location.lat,location.lon,location.address.display_text

HTTP status code 200

Body

Type: application/json

Schema:

Cinema Collection Schema

property	type	nullable	description
cinemas	array of `object`
id	string		identifier
slug	string		SEO friendly identifier
name	string		Cinema name / title
chain_id	string	✓	The identifier of the chain the cinema is a venue of.
city_id	string		The identifier of city the cinema is in.
telephone	string	✓	Telephone is a human-readable format.
email	string	✓	Cinema contact email address.
website	string	✓	URL to the cinema's website
booking_type	enum		Booking type indicates if and how the cinema's shows are generally bookable. Mostly it's set either to `external` or `null`. The type `internal` indicates that shows are bookable via this very API. The object is an enum, with one of the following required values: - `internal` - `external` - `null`
location	object
location.lat	number		latitude
location.lon	number		longitude
location.address	address
maccs_code	number	✓	MACCS code of the cinema
comscore_id	number	✓	Comscore Id of the cinema

Sub Schemas

`address` (object)

property	type	nullable	description
display_text	string		A string containing the human-readable address, ready to display
street	string	✓	Street name (in practice may also contain street number).
house	string	✓	House or street number. Example: `123 or 48A`
zipcode	string	✓	An alphanumeric string included in a postal address to facilitate mail sorting (a.k.a. post code, postcode, or ZIP code). Example: `10999`
city	string	✓	The localized city name.
state	string	✓	The division of a country, typically a first-level administrative division of a country and/or a geographical region.
state_abbr	string	✓	A code or abbreviation for the state division.
country	string	✓	The localized country name.
country_code	string		ISO 3166-1 alpha-2 code of the country.

Example:

{
  "cinemas": [
    {
      "id": "263",
      "name": "Kino International",
      "slug": "international-berlin",
      "telephone": "0 30 / 2 47 56 01 1",
      "website": "http://www.yorck.de",
      "booking_type": "external",
      "location": {
        "lat": 52.5201,
        "lon": 13.423,
        "address": {
          "display_text": "Karl-Marx-Allee 33, 10178, Berlin, Deutschland",
          "street": "Karl-Marx-Allee 33",
          "zipcode": "10178",
          "city": "Berlin",
          "country": "Deutschland",
          "country_code": "DE"
        }
      },
      "chain_id": "41"
    },
    {
      "id": "257",
      "name": "Zoo-Palast",
      "slug": "zoo-palast-berlin",
      "telephone": "01805222966",
      "website": "http://www.zoopalast-berlin.de/",
      "booking_type": "external",
      "location": {
        "lat": 52.5059,
        "lon": 13.3331,
        "address": {
          "display_text": "Hardenberg Straße 29a, 10623, Berlin, Deutschland",
          "street": "Hardenberg Straße 29a",
          "zipcode": "10623",
          "city": "Berlin",
          "country": "Deutschland",
          "country_code": "DE",
        }
      },
      "chain_id": null
    },
    {
      "id": "97",
      "name": "Cineplex Spandau",
      "slug": "cineplex-spandau-berlin",
      "telephone": "01805/050211",
      "website": "http://www.cineplex.de",
      "booking_type": "external",
      "location": {
        "lat": 52.5385,
        "lon": 13.2064,
        "address": {
          "display_text": "Havelstraße 20, 13597, Berlin, Deutschland",
          "street": "Havelstraße 20",
          "zipcode": "13597",
          "city": "Berlin",
          "country": "Deutschland"
          "country_code": "DE",
        }
      },
      "chain_id": "12"
    }
  ]
}

HTTP status code 400

Body

Type: application/json

Schema:

property	type	nullable	description
error	object
error.code	number	✓	error code intended for client side error handling
error.user_message	string	✓	error message intended to be display to the user
error.debug_message	string	✓	error message intended for the developer to help resolving the error

Example:

{
  "error": {
    "code": null,
    "user_message": "Uuups, we couldn't find what you are looking for.",
    "internal_message": "ArgumentError: failed to parse list of `chain_ids`"
  }
}

/cinemas/{cinema_id} get

get

Retrieves a cinema by it's identifier.

Request
Response

URI Parameters

cinema_id: required (string)
The cinema_id or slug of the cinema.

Query Parameters

lang: (string)
Specifies the language for the resource's content given as an ISO 639 locale code. See Localization for more.
Example: de

HTTP status code 200

Body

Type: application/json

Schema:

property	type	nullable	description
cinema	object
cinema.id	string		identifier
cinema.slug	string		SEO friendly identifier
cinema.name	string		Cinema name / title
cinema.chain_id	string	✓	The identifier of the chain the cinema is a venue of.
cinema.city_id	string		The identifier of city the cinema is in.
cinema.telephone	string	✓	Telephone is a human-readable format.
cinema.email	string	✓	Cinema contact email address.
cinema.website	string	✓	URL to the cinema's website
cinema.booking_type	enum		Booking type indicates if and how the cinema's shows are generally bookable. Mostly it's set either to `external` or `null`. The type `internal` indicates that shows are bookable via this very API. The object is an enum, with one of the following required values: - `internal` - `external` - `null`
cinema.location	object
cinema.location.lat	number		latitude
cinema.location.lon	number		longitude
cinema.location.address	address
cinema.maccs_code	number	✓	MACCS code of the cinema
cinema.comscore_id	number	✓	Comscore Id of the cinema

Sub Schemas

`address` (object)

property	type	nullable	description
display_text	string		A string containing the human-readable address, ready to display
street	string	✓	Street name (in practice may also contain street number).
house	string	✓	House or street number. Example: `123 or 48A`
zipcode	string	✓	An alphanumeric string included in a postal address to facilitate mail sorting (a.k.a. post code, postcode, or ZIP code). Example: `10999`
city	string	✓	The localized city name.
state	string	✓	The division of a country, typically a first-level administrative division of a country and/or a geographical region.
state_abbr	string	✓	A code or abbreviation for the state division.
country	string	✓	The localized country name.
country_code	string		ISO 3166-1 alpha-2 code of the country.

Example:

{
  "cinema": {
    "id": "1044",
    "name": "CineStar",
    "telephone": "0561/701710",
    "slug": "cinestar-kassel",
    "website": "http://www.cinestar.de",
    "bookable": "external",
    "location": {
      "lat": 51.3115,
      "lon": 9.49481,
      "address": {
        "display_text": "Karlsplatz 8, 34117, Kassel, Germany",
        "street": "Karlsplatz 8",
        "house": "8",
        "city": "Kassel",
        "zipcode": "34117",
        "country": "Deutschland",
        "country_code": "DE",
      }
    }
  }
}

HTTP status code 404

Body

Type: application/json

Schema:

property	type	nullable	description
error	object
error.code	number	✓	error code intended for client side error handling
error.user_message	string	✓	error message intended to be display to the user
error.debug_message	string	✓	error message intended for the developer to help resolving the error

Example:

{
  "error": {
    "code": 10007,
    "user_message": "Uuups, we couldn't find what you are looking for.",
    "internal_message": null
  }
}

Cinema Chains

The collection of chains.

/chains get head

get

Retrieve the list of all chains, optionally filtered.

head

Use HEAD requests to query total number / count of a chains. Allows to apply all filters as available via GET.

Retrieve the list of all chains, optionally filtered.

Request
Response

Query Parameters

countries: (string)
Filters the chains by country based on a single or a list of ISO 3166-1 alpha-2 codes. Fetch the Countries - index endpoint to see which countries are available.
Example: DE,AT

HTTP status code 200

Body

Type: application/json

Schema:

Cinema Chains Collection Schema

property	type	description
chains	array of `object`
id	string	The identifier of the cinema chain.
name	string	The name of the cinema chain.
websites	array of `string`	URLs of the website of the chain. Usually one per country.
countries	array of `string`	The countries (as ISO 3166-1 alpha-2 codes) in which the cinema chain has venues.

Example:

{
  "chains": [
    {
      "id": "1",
      "name": "AMC Theatres",
      "websites": [
        "https://www.amctheatres.com/"
      ],
      "countries": ["US"]
    },
    {
      "id": "2",
      "name": "UCI Kinowelt",
      "websites": [
        "http://www.uci-kinowelt.de",
        "http://www.uci-kinowelt.at"
      ],
      "countries": ["DE", "AT"]
    }
  ]
}

Movies

The collection of movies.

/movies get head

get

Retrieve a shallow list of movies (in theatres if not specified otherwise). See the fields query parameters default value for the list of included fields.

head

Use HEAD requests to query total number / count of a movies. Allows to apply all filters as available via GET.

Retrieve a shallow list of movies (in theatres if not specified otherwise). See the fields query parameters default value for the list of included fields.

Request
Response

Query Parameters

search_query: (string)
Filters the movies list by the search query. Therefore a regular expression applies to the list where the given string is used as the pattern part of the regex. The regex's options are always set to case insensitivity (/i).
Example: ^Spectre
search_field: (string)
Along with a search_query parameter provide the field to be searched in.
Fields: title, original_title, synopsis, cast.name, crew.name, production_company, website, keyword, original_language, genre
page_token: (string)
Returns the page for the given token based on the initial query. All other parameters will be ignored.
page_size: (integer - default: 100)
Specifies the page size to be used for token based pagination.
Example: 50
offset: (integer)
Skips over a number of elements by specifying an offset value for the query.
Example: 20
limit: (integer - default: unlimited)
Limits the number of elements on the response.
Example: 100
time_from: (string - default: beginning of today in UTC timezone)
Filters the list of movies to those having showtimes at the given point in time or later.
Time format: Any parsable date-time string should work, however ISO8601 as in RFC3339 is recommended.
Example: 2016-04-24T00:00:00-08:00
time_to: (string - default: infinity)
Filters the list of movies to those having showtimes at the given point in time or earlier.
Time format: Any parsable date-time string should work, however ISO8601 as in RFC3339 is recommended.
Example: 2016-05-01T00:00:00-08:00
chain_ids: (string)
Filters the list of movies to those having shown in any cinema of the given list of chains. Fetch the Cinema Chains - index endpoint to seek for chains.
Example: 1,2,3
city_ids: (string)
Filters the list of movies to those having showtimes in any cinema in the given city. Fetch the Cities - index endpoint to seek for cities.
Example: 1,2,3
location: (string)
Retrieve movies in a particular area by passing a geo loaction as center in the format lat,lon.
Example: 52.50,13.37
distance: (number - default: 20 - maximum: 50)
For retrieving movies in a particular area along with the location you may want to specify the maximum distance given in kilometers. Results will be sorted by distance in ascending order.
Example: 10
bounds: (string)
Limit movies to geographical polygon given as list of at least two points in the following format: (lat,lon),(lat,lon)[,(lat,lon)...]
When passing only two points a bounding box will be built. For polygons make sure there are no crossing edges by sorting the points appropriately.
Example: (52.1,13.15),(52.9,13.37)
countries: (string)
Filters the movies by country based on a single or a list of ISO 3166-1 alpha-2 codes. Fetch the Countries - index endpoint to see which countries are available.
Example: DE,AT
fields: (string - default: id,title,slug,poster_image_thumbnail)
Defines a list of fields for building the shallow list. It allows to include fields that are only included in the movie detail requests otherwise.
Add on: For poster_image and scene_images details can by omitted by appending .flat. See response schema for more.
Example: id,title,poster_image.flat,synopsis,trailers
all_fields: (boolean - default: false)
Whether the response should include all fields.
Hint: Passing a truthy value will suspend any given fields parameter.
min_poster_image_width: (integer - default: 500)
Sets a minimum width poster images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?fields=poster_image.flat without specifying a minimum width.
min_poster_image_thumbnail_width: (integer - default: 140)
Sets a minimum width poster thumbnail images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned.
min_scene_image_width: (integer - default: 1000)
Sets a minimum width scene images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?fields=scene_images.flat without specifying a minimum width.
lang: (string)
Specifies the language for the resource's content given as an ISO 639 locale code. See Localization for more.
Example: de
imdb_id: (string)
Retrieve movies by imdb_id.
Hint: Even though there is only one movie to be returned, the response is still an array of movies for the sake of consistency in the RESTful API Design.
Example: tt2379713
tmdb_id: (string)
Retrieve movies by tmdb_id.
Hint: Even though there is only one movie to be returned, the response is still an array of movies for the sake of consistency in the RESTful API Design.
Example: 206647
rentrak_film_id: (string)
Retrieve movies by rentrak_film_id.
Hint: Even though there is only one movie to be returned, the response is still an array of movies for the sake of consistency in the RESTful API Design.
Example: 74324
rentrak_release_id: (string)
Retrieve movies by rentrak_release_id.
Example: 74324
cinema_id: (string)
Filters the list of movies to those having showtimes in the given cinema.
include_outdated: (boolean - default: false)
Defines whether to include movies that have no showtimes anymore.
include_upcomings: (boolean - default: false)
Defines whether to include upcoming movies. Requirements: Only works in the context of a country which must be specified via the countries parameter.
release_date_from: (string - default: infinity)
Filters movies by release date. Matches all movies that have any of its release dates on the given date or later.
Date format: Any parsable date string should work, however YYYY-MM-DD is recommended.
Requirements: Only works in the context of a country which must be specified via the countries parameter.
Example: 2016-07-01
release_date_to: (string - default: infinity)
Filters movies by release date. Matches all movies that have any of its release dates on the given date or earlier.
Date format: Any parsable date string should work, however YYYY-MM-DD is recommended.
Requirements: Only works in the context of a country which must be specified via the countries parameter.
Example: 2017-12-31
genre_ids: (string)
Filters movies to being in any of the specified genres.
Example: 1,2,3

HTTP status code 200

Body

Type: application/json

Schema:

Movie Collection Schema

property	type	nullable	description
meta_info	object		Dictionary of meta data describing the current chunk of the movie list.
movies	array of `object`
id	string		identifier
slug	string		SEO friendly identifier
title	string	✓	Localized title of the movie.
original_title	string		Title of the movie in it's original language.
original_language	string	✓	The original language the movies is produced in as ISO 639-1 code.
synopsis	string	✓	Localized synopsis / description of the movie.
poster_image	one of: - `image` - `string`	✓	The localized movie poster image. By default represented as `image` object, holding URLs to multiple sizes of the very same image. In case of `?fields=poster_image.flat` it directly holds the URL to the movie images. The size can by controlled via the `min_poster_image_size` parameter.
poster_image_thumbnail	string	✓	URL to thumbnail sized version of the localized movie poster image.
scene_images	one of: - array of `image` - array of `string`	✓	Array of scene / still images of the movie. By default each image is represented as `image` object, holding URLs to multiple sizes of the very same image. In case of `?fields=scene_images.flat` the array contains all images only once directly by the URLs. The size can by controlled via the `min_scene_image_width` parameter.
runtime	integer	✓	The runtime of the movie in the given localization.
genres	array of `object`		The genres of the movie with localized titles.
id	string		The identifier of the genre, which is consistent through all locales.
name	string	✓	The localized title of the genre.
trailers	array of `trailer`
ratings	object		Dictionary of `rating` objects by platfrom. Available platfrom are `imdb`, `tmdb`, `rotten_tomatos`.
age_limits	object		Age limits as a dictionary of `string` by ISO 3166-1 alpha-2 country code. Example: `{ "DE": "12", "US": "PG-13" }`
age_limits_descriptors	object		Descriptors information with age rating for Germany (`DE`). Information is provided in English (`en`) and German (`de`) translations. It is different information that is visible in age_limits. Example: `{ "DE": {"age": "12", "descriptors": [{"en": "violence", "de": "Gewalt"}]} }`
release_dates	object		Dictionary of arrays of `release_date` objects by ISO 3166-1 alpha-2 country code.
website	string	✓	URL to the movie's website. May be localized.
production_companies	array of `string`	✓	The studios / companies that produced or were involved in producing the movie.
keywords	array of `string`	✓	List of keywords for the movie, e.g. to be used for SEO.
imdb_id	string	✓	The movie's identifier at http://www.imdb.com/
tmdb_id	string	✓	The movie's identifier at http://www.tmdb.org/
rentrak_film_id	string	✓	The movie's rentrak film identifier.
cast	array of `person`	✓	cast of the movie
crew	array of `person`	✓	crew of the movie. (for now only writer and director available)

Sub Schemas

`meta_info` (object)

property	type	nullable	description
range_from	number		Index of the first item in the current chunk of the list.
range_to	integer		Index of the last item in the current chunk of the list.
total_count	integer		Total number of items in the list.
page_index	integer	✓	Index of the current page. (Is only present when working with token based pagination.)
page_count	integer	✓	Total number of pages. (Is only present when working with token based pagination.)
next_page_token	string	✓	Token to retrieve the next page of the current list. (Is only present when working with token based pagination.)

`rating` (object)

property	type	nullable	description
value	number		Rating value, normally average value of all ratings. Example: `8.5`
vote_count	integer		Number of the rating's votes. Example: `129`

`release_date` (object)

property	type	description
locale	string	ISO 639 codes of the region's language.
region	string	The localized name of the region for the given release date or `null` if the release date is the same for the entire country.
date	string	The actual date in the format `YYYY-MM-DD`.

`image` (object)

An image object is a container to hold multiple resolutions / sizes of the very same image.

property	type	description
image_files	array of `object`	Array of files for the same image in different resolutions / sizes.
url	string	URL to the image file.
size	object	The pixel size of the image.
size.height	integer	The pixel height of the image.
size.width	integer	The pixel width of the image.

`trailer` (object)

property	type	nullable	description
language	string		Trailer language as ISO 639 code
is_official	boolean	✓	Indicates whether the trailer is provided my the movie's studio. This is currenly only supported for youtube trailers.
trailer_files	array of `object`		Array of files for the same trailer in different file formats and sizes
format	enum		The trailer media file format. The object is an enum, with one of the following required values: - `flv` - `webm` - `wmv` - `mp4` - `youtube`
transfert	string	✓	Pixel resolution of the video or `null` for `youtube` trailers. Example: `1280x720`
url	string		URL to the video file.

`person` (object)

property	type	description
id	string	unique identifier for the person
name	string	the person's full name
image	string	URL to a picture of the persion.
job	enum	The person's job or role, if he/she is a crew member. The object is an enum, with one of the following required values: - `writer` - `director`
character	string	The character or role the persion is acting / playing the movie, if he/she is a cast member.

Example:

{
  "movies": [
    {
      "id": "16917",
      "name": "The Hateful 8",
      "slug": "the-hateful-eight",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f328951.jpg"
    },
    {
      "id": "16977",
      "name": "Bibi & Tina - Mädchen gegen Jungs",
      "slug": "bibi-tina-maedchen-gegen-jungs",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f327472.jpg"
    },
    {
      "id": "12097",
      "name": "Alvin und die Chipmunks: Road Chip",
      "slug": "alvin-and-the-chipmunks-road-chip",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f302062.jpg"
    },
    {
      "id": "12189",
      "name": "The Revenant - Der Rückkehrer",
      "slug": "the-revenant",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f320061.jpg"
    },
    {
      "id": "12143",
      "name": "Star Wars: Das Erwachen der Macht",
      "slug": "star-wars-episode-vii-das-erwachen-der-macht",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f314679.jpg"
    },
    {
      "id": "12187",
      "name": "Ride Along: Next Level Miami",
      "slug": "ride-along-2",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f320052.jpg"
    },
    {
      "id": "14943",
      "name": "Ich bin dann mal weg",
      "slug": "ich-bin-dann-mal-weg",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f327212.jpg"
    },
    {
      "id": "17507",
      "name": "Daddy's Home - Ein Vater zu viel",
      "slug": "daddy-s-home-ein-vater-zu-viel",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f328948.jpg"
    },
    {
      "id": "12195",
      "name": "Die 5. Welle",
      "slug": "the-5th-wave",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f320131.jpg"
    },
    {
      "id": "16583",
      "name": "Sebastian und die Feuerretter",
      "slug": "sebastian-und-die-feuerretter",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f330512.jpg"
    },
    {
      "id": "16070",
      "name": "Creed - Rocky's Legacy",
      "slug": "creed",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f328091.jpg"
    },
    {
      "id": "12091",
      "name": "Die Peanuts - Der Film",
      "slug": "die-peanuts-der-film",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f288140.jpg"
    },
    {
      "id": "12209",
      "name": "Hilfe, ich hab' meine Lehrerin geschrumpft",
      "slug": "hilfe-ich-hab-meine-lehrerin-geschrumpft",
      "poster_image_thumbnail": "http://imageserver.krankikom.de/film/f321166.jpg"
    }
  ]
}

HTTP status code 400

Body

Type: application/json

Schema:

property	type	nullable	description
error	object
error.code	number	✓	error code intended for client side error handling
error.user_message	string	✓	error message intended to be display to the user
error.debug_message	string	✓	error message intended for the developer to help resolving the error

Example:

{
  "error": {
    "code": null,
    "user_message": "Uuups, we couldn't find what you are looking for.",
    "internal_message": "ArgumentError: failed to parse list of `chain_ids`"
  }
}

/movies/{movie_id} get

get

Retrieves a movie by it's identifier.

Request
Response

URI Parameters

movie_id: required (string)
The movie_id or slug of the movie.
Example: 12111

Query Parameters

fields: (string)
Defines a list of fields to be included with the movie item. By default, all fields are included.
Add on: For poster_image and scene_images details can by omitted by appending .flat. See response schema for more.
Example: id,title,poster_image.flat,synopsis,trailers
min_poster_image_width: (integer - default: 500)
Sets a minimum width poster images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?fields=poster_image.flat without specifying a minimum width.
min_poster_image_thumbnail_width: (integer - default: 140)
Sets a minimum width poster thumbnail images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned.
min_scene_image_width: (integer - default: 1000)
Sets a minimum width scene images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?fields=scene_images.flat without specifying a minimum width.
lang: (string)
Specifies the language for the resource's content given as an ISO 639 locale code. See Localization for more.
Example: de

HTTP status code 200

Body

Type: application/json

Schema:

Movie Item Response Schema

property	type	nullable	description
movie	object
movie.id	string		identifier
movie.slug	string		SEO friendly identifier
movie.title	string	✓	Localized title of the movie.
movie.original_title	string		Title of the movie in it's original language.
movie.original_language	string	✓	The original language the movies is produced in as ISO 639-1 code.
movie.synopsis	string	✓	Localized synopsis / description of the movie.
movie.poster_image	one of: - `image` - `string`	✓	The localized movie poster image. By default represented as `image` object, holding URLs to multiple sizes of the very same image. In case of `?fields=poster_image.flat` it directly holds the URL to the movie images. The size can by controlled via the `min_poster_image_size` parameter.
movie.poster_image_thumbnail	string	✓	URL to thumbnail sized version of the localized movie poster image.
movie.scene_images	one of: - array of `image` - array of `string`	✓	Array of scene / still images of the movie. By default each image is represented as `image` object, holding URLs to multiple sizes of the very same image. In case of `?fields=scene_images.flat` the array contains all images only once directly by the URLs. The size can by controlled via the `min_scene_image_width` parameter.
movie.runtime	integer	✓	The runtime of the movie in the given localization.
movie.genres	array of `object`		The genres of the movie with localized titles.
movie id	string		The identifier of the genre, which is consistent through all locales.
movie name	string	✓	The localized title of the genre.
movie.trailers	array of `trailer`
movie.ratings	object		Dictionary of `rating` objects by platfrom. Available platfrom are `imdb`, `tmdb`, `rotten_tomatos`.
movie.age_limits	object		Age limits as a dictionary of `string` by ISO 3166-1 alpha-2 country code. Example: `{ "DE": "12", "US": "PG-13" }`
movie.age_limits_descriptors	object		Descriptors information with age rating for Germany (`DE`). Information is provided in English (`en`) and German (`de`) translations. It is different information that is visible in age_limits. Example: `{ "DE": {"age": "12", "descriptors": [{"en": "violence", "de": "Gewalt"}]} }`
movie.release_dates	object		Dictionary of arrays of `release_date` objects by ISO 3166-1 alpha-2 country code.
movie.website	string	✓	URL to the movie's website. May be localized.
movie.production_companies	array of `string`	✓	The studios / companies that produced or were involved in producing the movie.
movie.keywords	array of `string`	✓	List of keywords for the movie, e.g. to be used for SEO.
movie.imdb_id	string	✓	The movie's identifier at http://www.imdb.com/
movie.tmdb_id	string	✓	The movie's identifier at http://www.tmdb.org/
movie.rentrak_film_id	string	✓	The movie's rentrak film identifier.
movie.cast	array of `person`	✓	cast of the movie
movie.crew	array of `person`	✓	crew of the movie. (for now only writer and director available)

Sub Schemas

`rating` (object)

property	type	nullable	description
value	number		Rating value, normally average value of all ratings. Example: `8.5`
vote_count	integer		Number of the rating's votes. Example: `129`

`release_date` (object)

property	type	description
locale	string	ISO 639 codes of the region's language.
region	string	The localized name of the region for the given release date or `null` if the release date is the same for the entire country.
date	string	The actual date in the format `YYYY-MM-DD`.

`image` (object)

An image object is a container to hold multiple resolutions / sizes of the very same image.

property	type	description
image_files	array of `object`	Array of files for the same image in different resolutions / sizes.
url	string	URL to the image file.
size	object	The pixel size of the image.
size.height	integer	The pixel height of the image.
size.width	integer	The pixel width of the image.

`trailer` (object)

property	type	nullable	description
language	string		Trailer language as ISO 639 code
is_official	boolean	✓	Indicates whether the trailer is provided my the movie's studio. This is currenly only supported for youtube trailers.
trailer_files	array of `object`		Array of files for the same trailer in different file formats and sizes
format	enum		The trailer media file format. The object is an enum, with one of the following required values: - `flv` - `webm` - `wmv` - `mp4` - `youtube`
transfert	string	✓	Pixel resolution of the video or `null` for `youtube` trailers. Example: `1280x720`
url	string		URL to the video file.

`person` (object)

property	type	description
id	string	unique identifier for the person
name	string	the person's full name
image	string	URL to a picture of the persion.
job	enum	The person's job or role, if he/she is a crew member. The object is an enum, with one of the following required values: - `writer` - `director`
character	string	The character or role the persion is acting / playing the movie, if he/she is a cast member.

Example:

{
  "movie": {
    "id": "12111",
    "slug": "spectre",
    "title": "Spectre",
    "poster_image_thumbnail": "http://image.tmdb.org/t/p/w154/lYb4V8fyFLnI3dstZVXGphI8NCs.jpg",
    "synopsis": "A cryptic message from Bond’s past sends him on a trail to uncover a sinister organization. While M battles political forces to keep the secret service alive, Bond peels back the layers of deceit to reveal the terrible truth behind SPECTRE.",
    "runtime": 148,
    "genres": [
      {
        "id": "0",
        "name": "Action"
      },
      {
        "id": "1",
        "name": "Adventure"
      },
      {
        "id": "4",
        "name": "Crime"
      }
    ],
    "poster_image": "http://image.tmdb.org/t/p/w500/lYb4V8fyFLnI3dstZVXGphI8NCs.jpg",
    "scene_images": [
      "http://image.tmdb.org/t/p/w1000/wVTYlkKPKrljJfugXN7UlLNjtuJ.jpg",
      "http://image.tmdb.org/t/p/w1000/ohKncfyZi0NLR1oyyz7ETRnxxWd.jpg",
      "http://image.tmdb.org/t/p/w1000/Jshz1Iv33im4hXhHJCI9FklihE.jpg",
      "http://image.tmdb.org/t/p/w1000/qSc4L05AnHbMpSk0bsHuX25vX4V.jpg",
      "http://image.tmdb.org/t/p/w1000/plxJs4AolooP2DvZ1zvtnDNQnAc.jpg",
      "http://image.tmdb.org/t/p/w1000/qnc8z8P8wrSxAVEQbu7AA4lEh0b.jpg",
      "http://image.tmdb.org/t/p/w1000/pshAYoppm19NQcLgqHfbxYwDnLs.jpg",
      "http://image.tmdb.org/t/p/w1000/s8oOZHNCQOCq2LqHf4ZF0PQaGhO.jpg",
      "http://image.tmdb.org/t/p/w1000/9tR4VrASkeNoUTBipg7RrcDtr7B.jpg",
      "http://image.tmdb.org/t/p/w1000/3Gy8bA8s6aabGJqTxZZ9WmrbgTB.jpg",
      "http://image.tmdb.org/t/p/w1000/jSNIAKD5pCyhjgJL9HZ3hsu19yD.jpg",
      "http://image.tmdb.org/t/p/w1000/5BP0kzd0EaYxkr2WzmEkejeI6u0.jpg",
      "http://image.tmdb.org/t/p/w1000/fa9qPNpmLtk7yC5KZj9kIxlDJvG.jpg",
      "http://image.tmdb.org/t/p/w1000/7hk665E1DrxfGkccEG5QOWADiSv.jpg",
      "http://image.tmdb.org/t/p/w1000/i0QNHMlRMmupQEDnluw3rXi70iv.jpg",
      "http://image.tmdb.org/t/p/w1000/nxc1bjB2z7XecOiPnsE1QpfYFpJ.jpg",
      "http://image.tmdb.org/t/p/w1000/1A7nZfkJTi9NzS8FBXvWYL1L7T.jpg",
      "http://image.tmdb.org/t/p/w1000/lFOy7pJ7TjXbNvvR25cKyxwBX3w.jpg",
      "http://image.tmdb.org/t/p/w1000/qlLqejv0jziYZ0JsUATfJkx8AZR.jpg",
      "http://image.tmdb.org/t/p/w1000/ozasA59FuPv1QBD2yUueCGmcInv.jpg",
      "http://image.tmdb.org/t/p/w1000/eF3OuOVqrFRbOTcuq8wd9tSzhFM.jpg",
      "http://image.tmdb.org/t/p/w1000/cNiO22mtARcyeNivzeON9sOvr65.jpg",
      "http://image.tmdb.org/t/p/w1000/9ePxZMRDB6RDoFx0C6QoVYQaXS1.jpg",
      "http://image.tmdb.org/t/p/w1000/w2M7eBdjhjMzzOaibOfKgnrXiAF.jpg",
      "http://image.tmdb.org/t/p/w1000/voLEXknqXl4UIJtevjWwKZWHWui.jpg",
      "http://image.tmdb.org/t/p/w1000/f0Og0XLwFHu7T4LKiANj6LKVHUB.jpg",
      "http://image.tmdb.org/t/p/w1000/1I1ocQ3aQl71KxyDawOst4VUAJb.jpg",
      "http://image.tmdb.org/t/p/w1000/tdYlYbZJxVFyGQUhSI0wb5Q516w.jpg",
      "http://image.tmdb.org/t/p/w1000/zyroNE8z0S7T56VClou4GABbwFj.jpg",
      "http://image.tmdb.org/t/p/w1000/o83PeQflGqdXZRf3R8O1lOIQK9p.jpg",
      "http://image.tmdb.org/t/p/w1000/t2UD4sHZfnY3zz2nXVwmaNAXI1U.jpg",
      "http://image.tmdb.org/t/p/w1000/2Dr1Tm9SGMl7TPhEhvaU8fQdgEo.jpg",
      "http://image.tmdb.org/t/p/w1000/BaBj3DJbjYIL8PzopJGwGqQ4u6.jpg",
      "http://image.tmdb.org/t/p/w1000/yywt40pjPuxobP7REGdXjdHz3IC.jpg",
      "http://image.tmdb.org/t/p/w1000/bh2Aqcx6ccr5BoW3AmSO6qlcyaY.jpg",
      "http://image.tmdb.org/t/p/w1000/xE6WIynVLwaIsp0X6OVQvT2wexH.jpg"
    ],
    "trailers": [
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": "1920x1080",
            "url": "https://www.youtube.com/watch?v=z4UDNzXD3qA"
          }
        ]
      },
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": "1920x1080",
            "url": "https://www.youtube.com/watch?v=ujmoYyEyDP8"
          }
        ]
      },
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": null,
            "url": "https://www.youtube.com/watch?v=7GqClqvlObY"
          }
        ]
      },
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": null,
            "url": "https://www.youtube.com/watch?v=LTDaET-JweU"
          }
        ]
      },
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": null,
            "url": "https://www.youtube.com/watch?v=l9hMaqdNzz8"
          }
        ]
      },
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": null,
            "url": "https://www.youtube.com/watch?v=z4UDNzXD3qA"
          }
        ]
      },
      {
        "language": "en",
        "is_official": null,
        "trailer_files": [
          {
            "format": "youtube",
            "transfert": null,
            "url": "https://www.youtube.com/watch?v=qLzErPYUb-8"
          }
        ]
      }
    ],
    "ratings": {
      "imdb": {
        "value": 6.8,
        "vote_count": 301698
      },
      "tmdb": {
        "value": 6.2,
        "vote_count": 3545
      }
    },
    "age_limits": {
      "BR": "14",
      "GB": "12A",
      "US": "PG-13",
      "DE": 12,
      "IT": "T",
      "FR": "U",
      "NL": "12",
      "SE": "11",
      "AU": "M",
      "BE": "12",
      "CA": "PG",
      "RU": "16+"
    },
    "release_dates": {
      "BR": [
        {
          "locale": "pt-BR",
          "region": null,
          "date": "2015-11-05"
        }
      ],
      "GB": [
        {
          "locale": "en-GB",
          "region": null,
          "date": "2015-10-26"
        }
      ],
      "US": [
        {
          "locale": "en-US",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "DE": [
        {
          "locale": "de-DE",
          "region": null,
          "date": "2015-11-05"
        }
      ],
      "IT": [
        {
          "locale": "it-IT",
          "region": null,
          "date": "2015-11-05"
        }
      ],
      "FR": [
        {
          "locale": "fr-FR",
          "region": null,
          "date": "2015-11-11"
        }
      ],
      "ES": [
        {
          "locale": "es-ES",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "NL": [
        {
          "locale": "nl-NL",
          "region": null,
          "date": "2015-10-29"
        }
      ],
      "SE": [
        {
          "locale": "sv-SE",
          "region": null,
          "date": "2015-10-30"
        }
      ],
      "IE": [
        {
          "locale": "en-IE",
          "region": null,
          "date": "2015-10-26"
        }
      ],
      "RU": [
        {
          "locale": "ru-RU",
          "region": null,
          "date": "2015-11-05"
        },
        {
          "locale": "ru-RU",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "AT": [
        {
          "locale": "de-AT",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "AU": [
        {
          "locale": "en-AU",
          "region": null,
          "date": "2015-11-12"
        }
      ],
      "BE": [
        {
          "locale": "fr-BE",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "CA": [
        {
          "locale": "en-CA",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "DK": [
        {
          "locale": "da-DK",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "FI": [
        {
          "locale": "fi-FI",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "IN": [
        {
          "locale": "hi-IN",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "KZ": [
        {
          "locale": "kk-KZ",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "MX": [
        {
          "locale": "es-MX",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "NO": [
        {
          "locale": "no-NO",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "UA": [
        {
          "locale": "uk-UA",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "AR": [
        {
          "locale": "es-AR",
          "region": null,
          "date": "2015-11-12"
        }
      ],
      "JP": [
        {
          "locale": "ja-JP",
          "region": null,
          "date": "2015-12-04"
        }
      ],
      "CH": [
        {
          "locale": "de-CH",
          "region": null,
          "date": "2015-11-05"
        }
      ],
      "PL": [
        {
          "locale": "pl-PL",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "PT": [
        {
          "locale": "pt-PT",
          "region": null,
          "date": "2015-11-05"
        }
      ],
      "BY": [
        {
          "locale": "be-BY",
          "region": null,
          "date": "2015-11-06"
        }
      ],
      "LU": [
        {
          "locale": "fr-LU",
          "region": null,
          "date": "2015-11-04"
        }
      ]
    }
  }
}

HTTP status code 404

Body

Type: application/json

Schema:

property	type	nullable	description
error	object
error.code	number	✓	error code intended for client side error handling
error.user_message	string	✓	error message intended to be display to the user
error.debug_message	string	✓	error message intended for the developer to help resolving the error

Example:

{
  "error": {
    "code": 10007,
    "user_message": "Uuups, we couldn't find what you are looking for.",
    "internal_message": null
  }
}

Genres

The collection of genres.

/genres get head

get

Retrieve the list of all genres, optionally filtered.

head

Use HEAD requests to query total number / count of a genres. Allows to apply all filters as available via GET.

Retrieve the list of all genres, optionally filtered.

Request
Response

Query Parameters

lang: (string)
Specifies the language for the resource's content given as an ISO 639 locale code. See Localization for more.
Example: de

HTTP status code 200

Body

Type: application/json

Schema:

Genre Collection Schema

property	type	nullable	description
genres	array of `object`
id	string		The identifier of the genre, which is consistent through all locales.
name	string	✓	The localized title of the genre.

Example:

{
  "genres": [
    {
      "id": "1",
      "title": "Drama"
    },
    {
      "id": "2",
      "title": "Science - Fiction"
    },
    {
      "id": "3",
      "title": "Action"
    },
    {
      "id": "4",
      "title": "Thriller"
    },
    {
      "id": "5",
      "title": "Comedy"
    }
  ]
}

Showtimes

The collection of showtimes.

/showtimes get head

get

Retrieve the list of all showtimes, optionally filtered.

head

Use HEAD requests to query total number / count of a showtimes. Allows to apply all filters as available via GET.

Retrieve the list of all showtimes, optionally filtered.

Request
Response

Query Parameters

min_poster_image_width: (integer - default: 500)
Sets a minimum width poster images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?movie_fields=poster_image.flat without specifying a minimum width.
min_poster_image_thumbnail_width: (integer - default: 140)
Sets a minimum width poster thumbnail images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned.
min_scene_image_width: (integer - default: 1000)
Sets a minimum width scene images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?movie_fields=scene_images.flat without specifying a minimum width.
fields: (string - default: id,cinema_id,movie_id,start_at,language,subtitle_language,attribute_codes,booking_type,auditorium,is_3d)
Defines a list of fields for building the shallow list. It allows to include fields that are only included in the showtime detail requests otherwise.
Example: id,cinema_id,start_at,cinema_movie_title,booking_link
all_fields: (boolean - default: false)
Whether the response should include all fields.
Hint: Passing a truthy value will suspend any given fields parameter.
search_query: (string)
Filters the showtimes list by the search query. Therefore a regular expression applies to the list where the given string is used as the pattern part of the regex. The regex's options are always set to case insensitivity (/i).
Example: ^Spectre
search_field: (string)
Along with a search_query parameter provide the field to be searched in.
Fields: cinema_movie_title
time_from: (string - default: beginning of today in UTC timezone)
Filters the showtimes to those starting at the given point in time or later.
Time format: Any parsable date-time string should work, however ISO8601 as in RFC3339 is recommended.
Example: 2016-04-24T00:00:00-08:00
time_to: (string - default: infinity)
Filters the showtimes to those starting at the given point in time or earlier.
Time format: Any parsable date-time string should work, however ISO8601 as in RFC3339 is recommended.
Example: 2016-05-01T00:00:00-08:00
city_ids: (string)
Filters the showtimes to those being shown in the given list of city_ids. Fetch the Cities - index endpoint to seek for cities.
Example: 1,2,3
location: (string)
Retrieve showtimes in a particular area by passing a geo loaction as center in the format lat,lon.
Example: 52.50,13.37
distance: (number - default: 20 - maximum: 50)
For retrieving showtimes in a particular area along with the location you may want to specify the maximum distance given in kilometers. Results will be sorted by distance in ascending order.
Example: 10
bounds: (string)
Limit showtimes to geographical polygon given as list of at least two points in the following format: (lat,lon),(lat,lon)[,(lat,lon)...]
When passing only two points a bounding box will be built. For polygons make sure there are no crossing edges by sorting the points appropriately.
Example: (52.1,13.15),(52.9,13.37)
countries: (string)
Filters the showtimes by country based on a single or a list of ISO 3166-1 alpha-2 codes. Fetch the Countries - index endpoint to see which countries are available.
Example: DE,AT
chain_ids: (string)
Filters the showtimes to those being shown in any cinema of the given list of chains. Fetch the Cinema Chains - index endpoint to seek for chains.
Example: 1,2,3
cinema_id: (string)
Retrieve showtimes for a particular cinema.
movie_id: (string)
Filter showtimes by movie_id to either a particular movie or absence/presence of a movie.
Hint: Showtimes may not be linked to a movie in case of them being published with a title that the system fails to find a unique movie for. This is most likely the case for events held in cinemas, which are not showing an actual movie. In order to associate showtimes without a movie client side, request the cinema_movie_title field on showtimes to be included with the response. See fields parameter for details.
Filtering null values: To retrieve only showtimes linked to a movie simply set the value of this parameter to !null. Likewise set it to null for retrieving only showtimes without linked movie.
Examples: 12111, null, !null
attribute_codes: (string)
Retrieve showtimes for given attribute_codes. This should be comma separated values for multiple attributes e.g attribute_codes=dbox,dub.
It works like inclusive OR. In above case it will list all showtimes with dbox OR dub attributes codes.
Example: 3d,dub,imax,2d
append: (string)
Tells the API to optionally include movies and/or cinemas related to the selected showtimes with the response.
Example: movies,cinemas
cinema_fields: (string)
Defines the list of fields for building the shallow list of cinemas. Is only relevant if cinemas are added to the response via the append parameter. Defaults to including all cinemas fields.
Example: id,name,location.lat,location.lon,location.address.display_text
movie_fields: (string - default: id,title,slug,poster_image_thumbnail)
Defines the list of fields for building the shallow list of movies. Is only relevant if movies are added to the response via the append parameter. See /movies endpoint for more on specifying fields.
Example: id,title,poster_image_thumbnail,ratings
changed_since: (string)
Fitlers the showtimes to only those that where either be created or updated since the specified timestamp.
You may combine this request header with the the value of the Last-Modified response header on subsequent requests.
Time format: The timestamp must be formattted either as RFC-822 date-time or as ISO8601 as in RFC3339
Example: Tue, 05 Jan 2021 05:47:45 GMT

HTTP status code 200

Body

Type: application/json

Schema:

Showtimes Collection Schema

property	type	nullable	description
showtimes	array of `object`
id	string		identifier
movie_id	string	✓	The identifier of the show's movie.
cinema_id	string		The identifier of the show's cinema.
start_at	string		Start time in ISO 8601 format set to the cinema's timezone.
attribute_codes	array of `string`	✓	List of version attributes by code. See /attributes endpoint for more.
language	string	✓	The language the movie is shown in as ISO 639 code.
subtitle_language	string	✓	The subtitle's language or languages as single ISO 639 code or comma separated list. If it is only known that the shows is subtitled, but not in which language, it will be set to `undetermined`.
auditorium	string	✓	Title of the auditorium.
booking_type	enum		Booking type indicates if and how the show is bookable. Mostly it's set either to `external` or `null`. The type `internal` indicates that shows are bookable via this very API. The object is an enum, with one of the following required values: - `internal` - `external` - `null`
cinema_movie_title	string	✓	The movie's title the cinema uses to publish it's showtimes.
booking_link	string	✓	The booking url (also refered to as deeplink) for ticketing of the show.
movie_page_link	string	✓	The movie page url that can be used for ticketing of the show if booking_link(deeplink) is not present in response.

Sub Schemas

`rating` (object)

property	type	nullable	description
value	number		Rating value, normally average value of all ratings. Example: `8.5`
vote_count	integer		Number of the rating's votes. Example: `129`

`release_date` (object)

property	type	description
locale	string	ISO 639 codes of the region's language.
region	string	The localized name of the region for the given release date or `null` if the release date is the same for the entire country.
date	string	The actual date in the format `YYYY-MM-DD`.

`image` (object)

An image object is a container to hold multiple resolutions / sizes of the very same image.

property	type	description
image_files	array of `object`	Array of files for the same image in different resolutions / sizes.
url	string	URL to the image file.
size	object	The pixel size of the image.
size.height	integer	The pixel height of the image.
size.width	integer	The pixel width of the image.

`trailer` (object)

property	type	nullable	description
language	string		Trailer language as ISO 639 code
is_official	boolean	✓	Indicates whether the trailer is provided my the movie's studio. This is currenly only supported for youtube trailers.
trailer_files	array of `object`		Array of files for the same trailer in different file formats and sizes
format	enum		The trailer media file format. The object is an enum, with one of the following required values: - `flv` - `webm` - `wmv` - `mp4` - `youtube`
transfert	string	✓	Pixel resolution of the video or `null` for `youtube` trailers. Example: `1280x720`
url	string		URL to the video file.

`person` (object)

property	type	description
id	string	unique identifier for the person
name	string	the person's full name
image	string	URL to a picture of the persion.
job	enum	The person's job or role, if he/she is a crew member. The object is an enum, with one of the following required values: - `writer` - `director`
character	string	The character or role the persion is acting / playing the movie, if he/she is a cast member.

Example:

{
  "showtimes": [
    {
      "id": "260_16583_201602011415",
      "start_at": "2016-02-01T14:15:00+01:00",
      "language": "de",
      "subtitle_language": null,
      "attribute_codes": [
        "3d"
      ],
      "auditorium": null,
      "is_3d": null,
      "movie_id": "16977",
      "cinema_id": "260",
      "booking_type": null,
      "booking_link": null,
      "movie_page_link": null
    },
    {
      "id": "260_12322_201602011600",
      "start_at": "2016-02-01T16:00:00+01:00",
      "language": "de",
      "subtitle_language": null,
      "attribute_codes": [
        "dub",
        "3d",
        "imax"
      ],
      "auditorium": null,
      "is_3d": null,
      "movie_id": "12322",
      "cinema_id": "260",
      "booking_type": "external",
      "booking_link": null,
      "movie_page_link": "https://www.basscoastculturalvenues.com/event-details/"
    },
    {
      "id": "260_16977_201602011620",
      "start_at": "2016-02-01T16:20:00+01:00",
      "language": "de",
      "subtitle_language": null,
      "attribute_codes": [
        "dub",
        "3d",
        "imax"
      ],
      "auditorium": null,
      "is_3d": null,
      "movie_id": "16977",
      "cinema_id": "260",
      "booking_type": "external",
      "booking_link": "https://www.yorck.de/checkout/step01?showid=1281745",
      "movie_page_link": "https://www.basscoastculturalvenues.com/event-details/"
    }
  ],
  "movies": [
    {
      "id": "16977",
      "parent_id": null,
      "is_special": false,
      "name": "Bibi & Tina - Mädchen gegen Jungs",
      "original_title": "Bibi & Tina - Mädchen gegen Jungs",
      "slug": "bibi-tina-maedchen-gegen-jungs",
      "poster_img_thumbnail": "http://imageserver.cinepass.de/movies/16977.jpg",
    },
    {
      "id": "10636",
      "parent_id": null,
      "is_special": false,
      "name": "Heidi",
      "original_title": "Heidi",
      "slug": "heidi-f322377",
      "poster_img_thumbnail": "http://imageserver.cinepass.de/movies/10636.jpg"
    }
  ],
  "cinemas": [
    {
      "id": "260",
      "name": "Filmtheater am Friedrichshain",
      "street": "Bötzowstraße 1-5",
      "zipcode": "10407",
      "telephone": "0 30/42 84 51 88",
      "lat": 52.5288,
      "lon": 13.4305,
      "image": "http://images.cinepass.de/c260.jpg",
      "slug": "filmtheater-am-friedrichshain-berlin",
      "website": "http://www.yorck.de",
      "bookable": "external",
      "cityname": "Berlin",
      "country": "DE"
    }
  ]
}

HTTP status code 400

Body

Type: application/json

Schema:

property	type	nullable	description
error	object
error.code	number	✓	error code intended for client side error handling
error.user_message	string	✓	error message intended to be display to the user
error.debug_message	string	✓	error message intended for the developer to help resolving the error

Example:

{
  "error": {
    "code": null,
    "user_message": "Uuups, we couldn't find what you are looking for.",
    "internal_message": "ArgumentError: failed to parse list of `chain_ids`"
  }
}

/showtimes/{id} get

get

Retrieves a showtime by it's identifier.

Request
Response

URI Parameters

showtime_id: required (string)
The showtime_id or slug of the showtime.
id: required (string)

Query Parameters

min_poster_image_width: (integer - default: 500)
Sets a minimum width poster images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?movie_fields=poster_image.flat without specifying a minimum width.
min_poster_image_thumbnail_width: (integer - default: 140)
Sets a minimum width poster thumbnail images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned.
min_scene_image_width: (integer - default: 1000)
Sets a minimum width scene images should have. The API will determine the best suitable image that has at least the given with. If no image has at least the given width, the next smaller will be returned. Setting it will also cause the API to only return one size per image instead of returning all sizes. The default only applies when fetching with ?movie_fields=scene_images.flat without specifying a minimum width.
append: (string)
Tells the API to optionally include the movie and/or cinema related to the selected showtime with the response.
Example: movie,cinema
movie_fields: (string - default: id,title,slug,poster_image_thumbnail)
Defines the list of the movie's fields that shall be included in the response. Is only relevant if the movie is added to the response via the append parameter. See /movies endpoint for more on specifying fields.
Example: id,title,poster_image_thumbnail,ratings

HTTP status code 200

Body

Type: application/json

Schema:

Showtime Details Schema

property	type	nullable	description
showtime	object
showtime.id	string		identifier
showtime.movie_id	string	✓	The identifier of the show's movie.
showtime.cinema_id	string		The identifier of the show's cinema.
showtime.start_at	string		Start time in ISO 8601 format set to the cinema's timezone.
showtime.attribute_codes	array of `string`	✓	List of version attributes by code. See /attributes endpoint for more.
showtime.language	string	✓	The language the movie is shown in as ISO 639 code.
showtime.subtitle_language	string	✓	The subtitle's language or languages as single ISO 639 code or comma separated list. If it is only known that the shows is subtitled, but not in which language, it will be set to `undetermined`.
showtime.auditorium	string	✓	Title of the auditorium.
showtime.booking_type	enum		Booking type indicates if and how the show is bookable. Mostly it's set either to `external` or `null`. The type `internal` indicates that shows are bookable via this very API. The object is an enum, with one of the following required values: - `internal` - `external` - `null`
showtime.cinema_movie_title	string	✓	The movie's title the cinema uses to publish it's showtimes.
showtime.booking_link	string	✓	The booking url (also refered to as deeplink) for ticketing of the show.
showtime.movie_page_link	string	✓	The movie page url that can be used for ticketing of the show if booking_link(deeplink) is not present in response.

Sub Schemas

`rating` (object)

property	type	nullable	description
value	number		Rating value, normally average value of all ratings. Example: `8.5`
vote_count	integer		Number of the rating's votes. Example: `129`

`release_date` (object)

property	type	description
locale	string	ISO 639 codes of the region's language.
region	string	The localized name of the region for the given release date or `null` if the release date is the same for the entire country.
date	string	The actual date in the format `YYYY-MM-DD`.

`image` (object)

An image object is a container to hold multiple resolutions / sizes of the very same image.

property	type	description
image_files	array of `object`	Array of files for the same image in different resolutions / sizes.
url	string	URL to the image file.
size	object	The pixel size of the image.
size.height	integer	The pixel height of the image.
size.width	integer	The pixel width of the image.

`trailer` (object)

property	type	nullable	description
language	string		Trailer language as ISO 639 code
is_official	boolean	✓	Indicates whether the trailer is provided my the movie's studio. This is currenly only supported for youtube trailers.
trailer_files	array of `object`		Array of files for the same trailer in different file formats and sizes
format	enum		The trailer media file format. The object is an enum, with one of the following required values: - `flv` - `webm` - `wmv` - `mp4` - `youtube`
transfert	string	✓	Pixel resolution of the video or `null` for `youtube` trailers. Example: `1280x720`
url	string		URL to the video file.

`person` (object)

property	type	description
id	string	unique identifier for the person
name	string	the person's full name
image	string	URL to a picture of the persion.
job	enum	The person's job or role, if he/she is a crew member. The object is an enum, with one of the following required values: - `writer` - `director`
character	string	The character or role the persion is acting / playing the movie, if he/she is a cast member.

Example:

{
  "showtime": {
    "id": "260_15916_201601291400",
    "movie_id": "15916",
    "cinema_id": "260",
    "start_at": "2016-01-29T14:00:00+01:00",
    "language": "de",
    "subtitle_language": null,
    "attribute_codes": [
      "dub",
      "3d",
      "imax"
    ],
    "auditorium": null,
    "is_3d": true,
    "booking_type": null,
    "booking_link": "https://www.yorck.de/checkout/step01?showid=1281745",
    "movie_page_link": "https://www.basscoastculturalvenues.com/event-details/"
  },
  "movie": {
    "id": "16977",
    "parent_id": null,
    "is_special": false,
    "name": "Bibi & Tina - Mädchen gegen Jungs",
    "original_title": "Bibi & Tina - Mädchen gegen Jungs",
    "slug": "bibi-tina-maedchen-gegen-jungs",
    "poster_img_thumbnail": "http://imageserver.krankikom.de/film/f327472.jpg"
  },
  "cinema": {
    "id": "260",
    "name": "Filmtheater am Friedrichshain",
    "street": "Bötzowstraße 1-5",
    "zipcode": "10407",
    "telephone": "0 30/42 84 51 88",
    "lat": 52.5288,
    "lon": 13.4305,
    "image": "http://images.cinepass.de/c260.jpg",
    "slug": "filmtheater-am-friedrichshain-berlin",
    "website": "http://www.yorck.de",
    "bookable": "external",
    "cityname": "Berlin",
    "country": "DE"
  }
}

HTTP status code 404

Body

Type: application/json

Schema:

property	type	nullable	description
error	object
error.code	number	✓	error code intended for client side error handling
error.user_message	string	✓	error message intended to be display to the user
error.debug_message	string	✓	error message intended for the developer to help resolving the error

Example:

{
  "error": {
    "code": 10007,
    "user_message": "Uuups, we couldn't find what you are looking for.",
    "internal_message": null
  }
}

Advanced

Connectivity

HTTPS only

The API uses TLS to provide a secure way to deliver its data. Even though the API just supplies cinema and showtime data, we think that it's the right thing to do to encrypt the entire traffic. Furthermore, we only support TLS v1.0, v1.1 and v1.2. We do not support SSL v2 or v3 for a good reason. If your client uses HTTP to connect, the API redirects (HTTP code 301) to https://api.internationalshowtimes.com/v5/.

IPv6 ready

We enabled IPv6 on api.internationalshowtimes.com and videos.internationalshowtimes.com improve connectivity and have your API client ready for the future. Read more about IPv6.

Get DNS AAAA records (IPv6) using dig: dig AAAA api.internationalshowtimes.com

What is IPv6 and why do we need it?
The Internet operates by transferring data between networks in packets. In order to communicate and send/receive packets of data, each host, computer or other device connected to the Internet must be identified by a unique IP address. IPv4 has approximately four billion IP addresses (the sequence of numbers assigned to each Internet-connected device). The explosion in the number of people, devices, and web services on the Internet means that IPv4 is running out of space. IPv6, the next-generation Internet protocol which provides more than 340 trillion, trillion, trillion addresses, will connect the billions of people not connected today, allow a huge range of devices to connect directly with one another, and help ensure the Internet can continue its current growth rate indefinitely. Both IPv4 and IPv6 (and many other protocols at the core of the Internet) were developed by the Internet Engineering Task Force (IETF).

Source

HTTP Caching

This API supports HTTP caching, which is highly recommended to take advantage of in order to avoid unnecessary transfer of data.

The main idea is that data will only be sent to the client, if something has changed. To make use of this approach this API provides a Last-Modified header for each response. Once the client receives it, it should save the modification date to pass it to subsequent requests using If-Modified-Since header. This header makes a request (GET or HEAD) conditional: the server will send back the requested data only if it has been modified after the given timestamp. Otherwise, an empty response with a 304 Not Modified status code will be returned. This is especially useful for checking about showtime updates frequently.

Learn more:

Understanding HTTP/304 Responses
HTTP Caching by Mozilla

Errors

Errors may be returned with a JSON payload which is structured as followed:

{
  "error": {
    "code": <Numeric error code>,
    "user_message": <string message ready to be display to the user>
    "debug_message": <string message intended for the developer to help resolving the error>
  }
}

The internal_message is not present for all errors and may not be exposed according to the apikey's permissions.

Error codes are structured by error domains:

Range	Error Domain
10000	General: Retrieving data (Cinemas, Movies, Showtimes etc.)
20000	Ticketing
30000	User management

Error Codes

Code	Error
10001	Service unavailable for maintenance
10002	Unauthorized due to missing `apikey`
10003	Unauthorized due to unknown `apikey`
10004	Requested countries are forbidden for given `apikey`
10005	Unauthorized due to expired `apikey`
10006	Parameter validation failed
10007	Resource not found
10008	Undefined route / endpoint
10009	Resource was deleted due to duplicate.
10010	No permission to access requested resource.

Maintenance

In case of maintenance either all calls or specific calls will return a 503 response with the following payload (body). Make sure you also check the error code 10001 given with the response payload.

{
  "error": {
    "code": 10001,
    "user_message": "service unavailable for maintenance"
  }
}

Code Examples

The following code examples fetch a list of movies from Great Britains cinemas.

cURL

curl -X "GET" "https://api.internationalshowtimes.com/v5/movies/?countries=GB" -H "X-API-Key: YOUR_API_KEY"

GO

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func sendList() {

    // Create client
    client := &http.Client{}

    // Create request
    req, err := http.NewRequest("GET", "https://api.internationalshowtimes.com/v5/movies/?countries=GB", nil)

    // Headers
    req.Header.Add("X-API-Key", "YOUR_API_KEY")

    parseFormErr := req.ParseForm()
    if parseFormErr != nil {
      fmt.Println(parseFormErr)    
    }

    // Fetch Request
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println("Failure : ", err)
    }

    // Read Response Body
    respBody, _ := ioutil.ReadAll(resp.Body)

    // Display Results
    fmt.Println("response Status : ", resp.Status)
    fmt.Println("response Headers : ", resp.Header)
    fmt.Println("response Body : ", string(respBody))
}

JavaScript + jQuery

jQuery.ajax({
    url: "https://api.internationalshowtimes.com/v5/movies/",
    type: "GET",
    data: {
        "countries": "GB",
    },
    headers: {
        "X-API-Key": "YOUR_API_KEY",
    },
})
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
    console.log(data);
})
.fail(function(jqXHR, textStatus, errorThrown) {
    console.log("HTTP Request Failed");
})
.always(function() {
    /* ... */
});

Java (Apache HttpClient via Fluent API)

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }

  private static void sendRequest() {

    try {

      // Create request
      Content content = Request.Get("https://api.internationalshowtimes.com/v5/movies/?countries=GB")

      // Add headers
      .addHeader("X-API-Key", "YOUR_API_KEY")

      // Fetch request and return content
      .execute().returnContent();

      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

Node.js

(function(callback) {
    'use strict';

    const httpTransport = require('https');
    const responseEncoding = 'utf8';
    const httpOptions = {
        hostname: 'api.internationalshowtimes.com',
        port: '443',
        path: '/v5/movies/?countries=GB',
        method: 'GET',
        headers: {"X-API-Key":"YOUR_API_KEY"}
    };
    httpOptions.headers['User-Agent'] = 'node ' + process.version;

    // Paw Store Cookies option is not supported

    const request = httpTransport.request(httpOptions, (res) => {
        let responseBufs = [];
        let responseStr = '';

        res.on('data', (chunk) => {
            if (Buffer.isBuffer(chunk)) {
                responseBufs.push(chunk);
            }
            else {
                responseStr = responseStr + chunk;            
            }
        }).on('end', () => {
            responseStr = responseBufs.length > 0 ? 
                Buffer.concat(responseBufs).toString(responseEncoding) : responseStr;

            callback(null, res.statusCode, res.headers, responseStr);
        });

    })
    .setTimeout(120000)
    .on('error', (error) => {
        callback(error);
    });
    request.write("")
    request.end();


})((error, statusCode, headers, body) => {
    console.log('ERROR:', error); 
    console.log('STATUS:', statusCode);
    console.log('HEADERS:', JSON.stringify(headers));
    console.log('BODY:', body);
});

PHP + cURL

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://api.internationalshowtimes.com/v5/movies/?countries=GB');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "X-API-Key: YOUR_API_KEY",
 ]
);


// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

Python + Requests

# Install the Python Requests library:
# `pip install requests`

import requests


def send_request():
    try:
        response = requests.get(
            url="https://api.internationalshowtimes.com/v5/movies/",
            params={
                "countries": "GB",
            },
            headers={
                "X-API-Key": "YOUR_API_KEY",
            },
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

Ruby

require 'net/http'
require 'net/https'

def send_request
  uri = URI('https://api.internationalshowtimes.com/v5/movies/?countries=GB')

  # Create client
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Create Request
  req =  Net::HTTP::Get.new(uri)
  # Add headers
  req.add_field "X-API-Key", "YOUR_API_KEY"

  # Fetch Request
  res = http.request(req)
  puts "Response HTTP Status Code: #{res.code}"
  puts "Response HTTP Response Body: #{res.body}"
rescue StandardError => e
  puts "HTTP Request failed (#{e.message})"
end

Swift

class MyRequestController {
    func sendRequest() {
        /* Configure session, choose between:
           * defaultSessionConfiguration
           * ephemeralSessionConfiguration
           * backgroundSessionConfigurationWithIdentifier:
         And set session-wide properties, such as: HTTPAdditionalHeaders,
         HTTPCookieAcceptPolicy, requestCachePolicy or timeoutIntervalForRequest.
         */
        let sessionConfig = URLSessionConfiguration.default

        /* Create session, and optionally set a URLSessionDelegate. */
        let session = URLSession(configuration: sessionConfig, delegate: nil, delegateQueue: nil)

        guard var URL = URL(string: "https://api.internationalshowtimes.com/v5/movies/") else {return}
        let URLParams = [
            "countries": "GB",
        ]
        URL = URL.appendingQueryParameters(URLParams)
        var request = URLRequest(url: URL)
        request.httpMethod = "GET"

        // Headers

        request.addValue("YOUR_API_KEY", forHTTPHeaderField: "X-API-Key")

        /* Start a new Task */
        let task = session.dataTask(with: request, completionHandler: { (data: Data?, response: URLResponse?, error: Error?) -> Void in
            if (error == nil) {
                // Success
                let statusCode = (response as! HTTPURLResponse).statusCode
                print("URL Session Task Succeeded: HTTP \(statusCode)")
            }
            else {
                // Failure
                print("URL Session Task Failed: %@", error!.localizedDescription);
            }
        })
        task.resume()
        session.finishTasksAndInvalidate()
    }
}


protocol URLQueryParameterStringConvertible {
    var queryParameters: String {get}
}

extension Dictionary : URLQueryParameterStringConvertible {
    /**
     This computed property returns a query parameters string from the given NSDictionary. For
     example, if the input is @{@"day":@"Tuesday", @"month":@"January"}, the output
     string will be @"day=Tuesday&month=January".
     @return The computed parameters string.
    */
    var queryParameters: String {
        var parts: [String] = []
        for (key, value) in self {
            let part = String(format: "%@=%@",
                String(describing: key).addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)!,
                String(describing: value).addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)!)
            parts.append(part as String)
        }
        return parts.joined(separator: "&")
    }

}

extension URL {
    /**
     Creates a new URL by adding the given query parameters.
     @param parametersDictionary The query parameter dictionary to add.
     @return A new URL.
    */
    func appendingQueryParameters(_ parametersDictionary : Dictionary<String, String>) -> URL {
        let URLString : String = String(format: "%@?%@", self.absoluteString, parametersDictionary.queryParameters)
        return URL(string: URLString)!
    }
}

International Showtimes API

Introduction

Get all cinemas in a specific country

Get all cinemas at a specific coordinate within a distance of 30 kilometres.

How to get all movies playing in a particular cinema

Search for a movie by german title

Get a list of upcoming movies for Germany

Fetch only a subset of available fields for a particular movie

Get all showtimes of a movie playing in all theatres within a radius of 30 kilometres around a certain coordinate

Get all showtimes per movie in a specific City

URL parameter lang

HTTP Header Accept-Language

Identifiers

JSON Keys

2024-11-13:

New

2023-12-14:

New

2023-01-18:

New

2021-01-14:

New

2019-05-05: V4 → V5

New

Model Updates

API Endpoints

Attributes

get /attributes

HTTP status code 200

Body

Attributes Collection Schema

head /attributes

HTTP status code 200

Headers

Locales

get /locales

HTTP status code 200

Body

head /locales

HTTP status code 200

Headers

Countries

get /countries

HTTP status code 200

Body

Country Collection Schema

head /countries

HTTP status code 200

Headers

Cities

get /cities

Query Parameters

HTTP status code 200

Body

City Collection Schema

Sub Schemas

meta_info (object)

head /cities

HTTP status code 200

Headers

Cinemas

get /cinemas

Query Parameters

HTTP status code 200

Body

Cinema Collection Schema

Sub Schemas

address (object)

HTTP status code 400

Body

head /cinemas

HTTP status code 200

Headers

get /cinemas/{cinema_id}

URI Parameters

Query Parameters

HTTP status code 200

Body

Sub Schemas

address (object)

URL parameter `lang`

HTTP Header `Accept-Language`

`meta_info` (object)

`address` (object)

`address` (object)

`meta_info` (object)

`rating` (object)

`release_date` (object)

`image` (object)

`trailer` (object)

`person` (object)

`rating` (object)

`release_date` (object)

`image` (object)

`trailer` (object)

`person` (object)