API Endpoints

Locales

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

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.

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.

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.

Cities

The collection of cities.

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.

Cinemas

The collection of cinemas.

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.

get

Retrieves a cinema by it's identifier.

Cinema Chains

The collection of chains.

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.

Movies

The collection of movies.

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.

get

Retrieves a movie by it's identifier.

Genres

The collection of genres.

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.

Showtimes

The collection of showtimes.

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.

get

Retrieves a showtime by it's identifier.

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:

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:

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

Error Codes

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

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