International Showtimes API by CINEPASS

Version: 4

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

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/v4/cinemas/" -H "Authorization: Token token=YOUR_API_KEY"
HTTP Header 'X-API-Key'
- Example: curl "https://api.internationalshowtimes.com/v4/cinemas/" -H "X-Api-Key: YOUR_API_KEY"
URL parameter
- Example: curl "https://api.internationalshowtimes.com/v4/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/v4/cinemas/?countries=DE

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

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

How to get all movies playing in a particular cinema

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

Search for a movie by german title

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

Get a list of upcoming movies for Germany

GET https://api.internationalshowtimes.com/v4/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/v4/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/v4/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/v4/showtimes?city_ids=1&movie_id=12345

Localization

Many data values are available in different languages and locales. For example on cinemas the name of the city may change depending on the language. Movies typically have different titles in each country. Also media data such as movie posters and trailers are localized.

To specify the locale for retrieving the data include a supported locale via one of the following ways. If not specified the data is returning in english. A list of supported locales can be retrieved from the Locale - index endpoint.

Each response comes with a Content-Language HTTP Header, which allows for checking the used locale.

URL parameter `lang`

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

HTTP Header `Accept-Language`

Any valid value as specified in RFC2616 will be handled.

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

When testing the API via browser or using it via Ajax, the browser will automatically set a Accept-Language header.

For the majority of bare locales the API add the locales main country as fallback.
For example: de → de-DE or en → en-US

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 it 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

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"}]}}

2019-08-09:

Update

Add fallbacks for locales, e.g. de → de, de-DE or en-US → en-US, en

Model Updates

Cinema:

change	description
new	`city_id`

2019-06-13:

Add request timeouts

2019-03-19:

Model Updates

Country:

change	description
new	`name`

2018-10-31:

New

Cinemas endpoint
- Added ability to query cinemas having showtimes for a selected movie.

Update

Cinemas endpoint
- location and distance based requests now return cinemas sorted by distance in ascending order
Showtimes endpoint
- changed default value of time_to query parameter to infinity

2018-10-10:

New

Added X-Total-Count header allowing query only counts via HEAD requests

2018-10-06:

New

Cinemas endpoint
- added search (by name, website or zipcode)

2018-09-03:

New

Cinemas endpoint
- added fields parameter
Movies endpoint
- added location filter
Showtimes endpoint
- added search (by cinema_movie_title)

2018-02-08:

Model Updates

Showtime:

change	description
new	`is_imax`

2017-12-10:

New

Showtimes endpoint
- added null and !null filters to movie_id parameter
- added fields parameter

Model Updates

Showtime:

change	description
updated	`movie_id` is now `nullable`

2017-03-30:

New

Movies endpoint
- added genre_ids parameter

2016-12-09:

New

Movies endpoint
- added chain_ids parameter

2016-09-26:

New

Movies endpoint
- added tmdb_id parameter

2016-09-05:

New

Movies endoint
- added parameters to retrieve upcoming movies:
  - include_upcomings
  - release_date_from
  - release_date_to

2016-07-29:

New

Cinemas endpoint
- added city_ids parameter
Movies endpoint
- implemented city_ids parameter
Showtimes endoint
- added city_ids parameter

2016-04-25:

Update

Movies endpoint
- changed date_from and date_to parameters to time_from and time_to
Showtimes endoint
- changed date_from and date_to parameters to time_from and time_to

2016-04-06: V3 → V4

Model Updates

Country:

change	description
removed	`id`

Cinema:

Combined all location related properties in a nested location object.

change	description
renamed	`lat` → `location.lat`
renamed	`lon` → `location.lon`
renamed update	`street` → `location.address.street` may not include the house number anymore
renamed	`cityname` → `location.address.city`
renamed	`country` → `location.address.country_code`
renamed update	`bookable` → `booking_type` changed `"no"` to `null`
new	`location.address.house`
new	`location.address.display_text`

Movies:

The movie model has been completely overhauled.

change	description
renamed	`name` → `title`
renamed	`description` → `synopsis`
renamed	`poster_img` → `poster_image`
renamed	`poster_img_thumbnail` → `poster_image_thumbnail`
renamed update	`trailer_screen` → `scene_images` change to `array` of image urls
update	`genres` change to `array` of object
hidden	`preview_id`
removed	`imdb_ratings` is not part of new `ratings` property
updated	`cast` add more properties to persons
updated	`crew` add more properties to persons
new	`keywords`
new	`ratings`
new	`original_language`
new	`release_dates`
new	`website`
new	`production_companies`
new	`rentrak_film_id`

Showtimes

change	description
renamed update	`bookable` → `booking_type` changed `"no"` to `null`
new	`cinema_movie_website`

legend
new	field is completely new, there is no relation to any existing field of the previous api version
renamed	field has been renamed, values stay the same
hidden	may be still present but is not documented anymore. Might be used internally and has some likelihood to be removed
removed	field has been removed
updated	values of the field have slightly changed

New

new Cinema Chain endpoint
Cinema endpoint:
- added chain filter
- added pagination
new Genres endpoint
Movies endpoint
- added countries filter
- added images_width parameters (list & item)
- added pagination
- added rentrak_film_id parameter
Showtimes endoint
- added chain filter
- added countries filter
- omit movies and cinemas unless appended explicitly
- added ability to customize movie and cinema fields

API Endpoints

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
Hint: For searching in localized fields such as title or synopsis it is important to also specify the locale to search in via the lang query parameter.
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,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
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

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/v4/.

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.
10011	Timeout

Code Examples

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

cURL

curl -X "GET" "https://api.internationalshowtimes.com/v4/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/v4/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/v4/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/v4/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: '/v4/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/v4/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/v4/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/v4/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/v4/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 by CINEPASS

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

2019-08-09:

Update

Model Updates

2019-06-13:

2019-03-19:

Model Updates

2018-10-31:

New

Update

2018-10-10:

New

2018-10-06:

New

2018-09-03:

New

2018-02-08:

Model Updates

2017-12-10:

New

Model Updates

2017-03-30:

New

2016-12-09:

New

2016-09-26:

New

2016-09-05:

New

2016-07-29:

New

2016-04-25:

Update

2016-04-06: V3 → V4

Model Updates

New

API Endpoints

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

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)