Contents

Endpoints

Cinemas

Operations about cinemas

Relative to https://api.showtimes-api.com/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 account. An account with Ultra in one or more countries has 20. An account with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. All the keys of an account share the limit. The limit is not for each country. The error message gives the limit that applied.
  • 500 Internal Server Error – something went wrong on our end.
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 account. An account with Ultra in one or more countries has 20. An account with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. All the keys of an account share the limit. The limit is not for each country. The error message gives the limit that applied.
  • 500 Internal Server Error – something went wrong on our end.
Example response
{
  "id": 748,
  "chain": "picturehouse",
  "name": "Finsbury Park",
  "address": "Unit 1, Cinema LS, 17 City N Pl, Finsbury Park, London, N4 3FU",
  "latitude": 51.565151,
  "longitude": -0.107574,
  "link": "https://www.picturehouses.com/cinema/finsbury-park",
  "google_place_id": "ChIJgdX8IZsbdkgRCb-4YbTyeWI",
  "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 account. An account with Ultra in one or more countries has 20. An account with Lite in all its countries has 1, and 1000 requests each day. The day starts at 00:00 UTC. All the keys of an account share the limit. The limit is not for each country. The error message gives the limit that applied.
  • 500 Internal Server Error – something went wrong on our end.
Example response
{
  "id": 748,
  "chain": "picturehouse",
  "name": "Finsbury Park",
  "address": "Unit 1, Cinema LS, 17 City N Pl, Finsbury Park, London, N4 3FU",
  "latitude": 51.565151,
  "longitude": -0.107574,
  "link": "https://www.picturehouses.com/cinema/finsbury-park",
  "google_place_id": "ChIJgdX8IZsbdkgRCb-4YbTyeWI",
  "closed": false,
  "country": "GB",
  "currency": "GBP"
}