Contents

Cinemas

Operations about cinemas

Relative to https://uk-cinema-api.co.uk/api/v4.

Get cinemas

GET/cinemas

Get a paginated list of cinemas.

Parameters

page integer in query

Page offset to fetch.

Default: 1.

items integer in query

Number of items to return per page.

Default: 20.

country string in query

Get results only for these countries: comma-separated ISO 3166-1 alpha-2 codes, for example IE or GB,IE. Without it, you get all the countries that your key includes. A country that your key does not include gives 403. A country that the API does not serve gives 400. GET /countries lists both.

latitude number in query

Latitude of the center of the search, in decimal degrees. Send it with longitude and radius_km. If you send one of these three parameters, you must send all three.

longitude number in query

Longitude of the center of the search, in decimal degrees (see latitude).

radius_km number in query

Get results only for cinemas in this distance from latitude and longitude, in kilometres. The distance is the great-circle distance to the cinema. The value must be more than 0 and not more than 100 (see latitude).

Response

200 Returns cinemas with pagination metadata. (CinemasResponse)

Errors: 400, 401, 403, 429, 500

400 Bad request – e.g. an invalid cursor, a country the API does not serve, a filter that is not valid, or a query parameter that the endpoint does not have. The message names the parameter.
401 Unauthorized – the request requires valid authentication.
403 Forbidden – authentication succeeded but access is denied (e.g., expired subscription, or a country your key does not include).
429 Too Many Requests – the limit is 5 requests per second for a Pro key. A key with Ultra in one or more countries has 20. A key with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. The limit is for the key, not for each country. The error message gives the limit that applied.
500 Internal Server Error – something went wrong on our end.

const response = await fetch("https://uk-cinema-api.co.uk/api/v4/cinemas", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
})
const body = await response.json()

import requests

response = requests.get(
    "https://uk-cinema-api.co.uk/api/v4/cinemas",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
)
body = response.json()

require "json"
require "net/http"

response = Net::HTTP.get_response(
  URI("https://uk-cinema-api.co.uk/api/v4/cinemas"),
  {"Authorization" => "Bearer YOUR_API_TOKEN"}
)
body = JSON.parse(response.body)

Example response

{
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_count": 562
  },
  "data": [
    {
      "id": 495,
      "chain": "odeon_gb",
      "name": "London West End",
      "address": "38 Leicester Square, London, WC2H 7DX",
      "latitude": 51.5104,
      "longitude": -0.1293,
      "link": "https://www.odeon.co.uk/cinemas/london-west-end",
      "google_place_id": "ChIJc2nSALkEdkgRkuoJJBfzkUI",
      "closed": false,
      "country": "GB",
      "currency": "GBP"
    }
  ]
}

Show all 22 lines

Get cinema

GET/cinemas/{id}

Return a cinema.

Parameters

id integer in path required: Cinema ID.
country string in query: Get results only for these countries: comma-separated ISO 3166-1 alpha-2 codes, for example IE or GB,IE. Without it, you get all the countries that your key includes. A country that your key does not include gives 403. A country that the API does not serve gives 400. GET /countries lists both.

Response

200 Returns a cinema. (Cinema)

Errors: 400, 401, 403, 404, 429, 500

400 Bad request – e.g. an invalid cursor, a country the API does not serve, a filter that is not valid, or a query parameter that the endpoint does not have. The message names the parameter.
401 Unauthorized – the request requires valid authentication.
403 Forbidden – authentication succeeded but access is denied (e.g., expired subscription, or a country your key does not include).
404 Not found
429 Too Many Requests – the limit is 5 requests per second for a Pro key. A key with Ultra in one or more countries has 20. A key with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. The limit is for the key, not for each country. The error message gives the limit that applied.
500 Internal Server Error – something went wrong on our end.

const response = await fetch("https://uk-cinema-api.co.uk/api/v4/cinemas/748", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
})
const body = await response.json()

import requests

response = requests.get(
    "https://uk-cinema-api.co.uk/api/v4/cinemas/748",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
)
body = response.json()

require "json"
require "net/http"

response = Net::HTTP.get_response(
  URI("https://uk-cinema-api.co.uk/api/v4/cinemas/748"),
  {"Authorization" => "Bearer YOUR_API_TOKEN"}
)
body = JSON.parse(response.body)

Example response

{
  "id": 495,
  "chain": "odeon_gb",
  "name": "London West End",
  "address": "38 Leicester Square, London, WC2H 7DX",
  "latitude": 51.5104,
  "longitude": -0.1293,
  "link": "https://www.odeon.co.uk/cinemas/london-west-end",
  "google_place_id": "ChIJc2nSALkEdkgRkuoJJBfzkUI",
  "closed": false,
  "country": "GB",
  "currency": "GBP"
}

Get cinema by chain and external ID

GET/cinemas/{chain}/external/{external_id}

Get a cinema by cinema chain and the chain's native external ID.

Parameters

chain ChainEnum in path required: The cinema chain identifier.
external_id string in path required: The cinema chain's native cinema identifier.
country string in query: Get results only for these countries: comma-separated ISO 3166-1 alpha-2 codes, for example IE or GB,IE. Without it, you get all the countries that your key includes. A country that your key does not include gives 403. A country that the API does not serve gives 400. GET /countries lists both.

Response

200 Returns a cinema matching the external ID. (Cinema)

Errors: 400, 401, 403, 404, 429, 500

400 Bad request – e.g. an invalid cursor, a country the API does not serve, a filter that is not valid, or a query parameter that the endpoint does not have. The message names the parameter.
401 Unauthorized – the request requires valid authentication.
403 Forbidden – authentication succeeded but access is denied (e.g., expired subscription, or a country your key does not include).
404 Not found
429 Too Many Requests – the limit is 5 requests per second for a Pro key. A key with Ultra in one or more countries has 20. A key with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. The limit is for the key, not for each country. The error message gives the limit that applied.
500 Internal Server Error – something went wrong on our end.

const response = await fetch("https://uk-cinema-api.co.uk/api/v4/cinemas/picturehouse/external/029", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
})
const body = await response.json()

import requests

response = requests.get(
    "https://uk-cinema-api.co.uk/api/v4/cinemas/picturehouse/external/029",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
)
body = response.json()

require "json"
require "net/http"

response = Net::HTTP.get_response(
  URI("https://uk-cinema-api.co.uk/api/v4/cinemas/picturehouse/external/029"),
  {"Authorization" => "Bearer YOUR_API_TOKEN"}
)
body = JSON.parse(response.body)

Example response

{
  "id": 495,
  "chain": "odeon_gb",
  "name": "London West End",
  "address": "38 Leicester Square, London, WC2H 7DX",
  "latitude": 51.5104,
  "longitude": -0.1293,
  "link": "https://www.odeon.co.uk/cinemas/london-west-end",
  "google_place_id": "ChIJc2nSALkEdkgRkuoJJBfzkUI",
  "closed": false,
  "country": "GB",
  "currency": "GBP"
}