Chains endpoints | UK Cinema API

Get chains

GET/chains

Get a list of all cinema chains that have at least one cinema in the countries the request reads, with cinema counts.

Parameters

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 chains with metadata. (ChainsResponse)

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/chains", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
})
const body = await response.json()

import requests

response = requests.get(
    "https://uk-cinema-api.co.uk/api/v4/chains",
    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/chains"),
  {"Authorization" => "Bearer YOUR_API_TOKEN"}
)
body = JSON.parse(response.body)

Example response

{
  "meta": {
    "total_count": 51
  },
  "data": [
    {
      "id": "arc_cinema",
      "name": "Arc Cinema",
      "cinemas_count": 8
    }
  ]
}

Get chain

GET/chains/{id}

Returns a single cinema chain by its identifier.

Parameters

id ChainEnum in path required: Chain 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 chain. (Chain)

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/chains/picturehouse", {
  headers: { Authorization: "Bearer YOUR_API_TOKEN" },
})
const body = await response.json()

import requests

response = requests.get(
    "https://uk-cinema-api.co.uk/api/v4/chains/picturehouse",
    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/chains/picturehouse"),
  {"Authorization" => "Bearer YOUR_API_TOKEN"}
)
body = JSON.parse(response.body)

Example response

{
  "id": "arc_cinema",
  "name": "Arc Cinema",
  "cinemas_count": 8
}

Get chain cinemas

GET/chains/{id}/cinemas

Get a paginated list of cinemas belonging to a specific chain.

Parameters

id ChainEnum in path required

Chain identifier.

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.

Response

200 Returns cinemas with pagination metadata. (CinemasResponse)

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