API Endpoints


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


Retrieve the list of all attributes.


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


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


Retrieve the list of all available locales.


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


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.


Retrieve the list of all countries.


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


The collection of cities.


Retrieve the list of all cities, optionally filtered.


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


The collection of cinemas.


Retrieve the list of all cinemas, optionally filtered.


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


Retrieves a cinema by it's identifier.

Cinema Chains

The collection of chains.


Retrieve the list of all chains, optionally filtered.


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


The collection of movies.


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.


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


Retrieves a movie by it's identifier.


The collection of genres.


Retrieve the list of all genres, optionally filtered.


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


The collection of showtimes.


Retrieve the list of all showtimes, optionally filtered.


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


Retrieves a showtime by it's identifier.



HTTPS only

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

IPv6 ready

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

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

What is IPv6 and why do we need it?

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


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:


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:

RangeError Domain
10000General: Retrieving data (Cinemas, Movies, Showtimes etc.)
30000User management

Error Codes

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


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

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

Code Examples

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


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


package main

import (

func sendList() {

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

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

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

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

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

    url: "https://api.internationalshowtimes.com/v5/movies/",
    type: "GET",
    data: {
        "countries": "GB",
    headers: {
        "X-API-Key": "YOUR_API_KEY",
.done(function(data, textStatus, jqXHR) {
    console.log("HTTP Request Succeeded: " + jqXHR.status);
.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) {

  private static void sendRequest() {

    try {

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

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

      // Fetch request and return content

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


(function(callback) {
    'use strict';

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

    // Paw Store Cookies option is not supported

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

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

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

    .on('error', (error) => {

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



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

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

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

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

// Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [

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

Python + Requests

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

import requests

def send_request():
        response = requests.get(
                "countries": "GB",
                "X-API-Key": "YOUR_API_KEY",
        print('Response HTTP Status Code: {status_code}'.format(
        print('Response HTTP Response Body: {content}'.format(
    except requests.exceptions.RequestException:
        print('HTTP Request failed')


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

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

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

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

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


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

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

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

        // Headers

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

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

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