Contents

Films

Operations about films

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

Get films

GET/films

Get a paginated list of films currently showing in cinemas in the countries the request reads.

Parameters

page integer in query

Page offset to fetch.

Default: 1.

items integer in query

Number of items to return per page.

Default: 20.

cursor string in query

Use cursor pagination. Send an empty cursor for the first page. Then send meta.next_cursor from each response as cursor. When next_cursor is null, you have all the results.

A cursor walk gives films in id order, not in page order. You get a film that is added during the walk only if its id is after the cursor.

With a cursor, meta has next_cursor and not page, and the API ignores the page parameter. You cannot use cursor with search_query.

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.

cinema_id integer in query

Filter by a specific cinema.

include_outdated boolean in query

Include films that are no longer showing in cinemas.

Default: false.

search_query string in query

Search for films by title, director name, TMDB ID, or IMDB ID.

tmdb_id integer in query

Filter by a specific TMDB ID.

imdb_id string in query

Filter by a specific IMDB ID.

Response

200 Returns films with pagination metadata. (FilmsResponse)

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

import requests

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

Example response

{
  "meta": {
    "page": 1,
    "per_page": 20,
    "total_count": 1116
  },
  "data": [
    {
      "id": 296557755,
      "title": "Scream 7",
      "original_title": "Scream 7",
      "events_count": 17308,
      "imdb_id": "tt27047903",
      "tmdb_id": 1159559,
      "release_year": 2026,
      "runtime": 114,
      "original_language": "eng"
    }
  ]
}

Get film

GET/films/{id}

Returns a film.

Parameters

id integer in path required: Film 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 film. (Film)

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

import requests

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

Example response

{
  "id": 296557755,
  "title": "Scream 7",
  "original_title": "Scream 7",
  "events_count": 17308,
  "imdb_id": "tt27047903",
  "tmdb_id": 1159559,
  "release_year": 2026,
  "runtime": 114,
  "original_language": "eng"
}