Method name
GET filmShowTimes
Description
Returns showtimes for selected film at nearest cinemas. Results are sorted by distance.
Important Notes
In line with cinema industry practice, showtimes after midnight are treated as part of the previous day. The 24 hour period is treated as 03:00 – 02:59 (rather than 00:00 – 23:59). For example, cinemas may publish the following showtimes for 1st January: 10:00, 13:00, 17:00, 21:00, 01:00. The final time is treated as still being on 1st January, and not 2nd January. When requesting times for 1st January from our API, you will receive all five showtimes.
When highly anticipated films are released, the first showing may be at midnight on the official release day, but is recorded in our database as a time for the previous day. For example, if a film is officially released on 1st November, some cinemas may show it at 00:01 on 1st November (actual time and date). However, cinemas will publish this time as being part of the 31st October schedule because it starts before 02:59.
Showtimes are always returned as the times published on the originating cinema’s website. They are not adjusted for timezones or daylight savings.
Example request
filmShowTimes/?film_id=12345&date=2018-04-12&n=10
Required headers
| Sent header | Description | Data type | Optional / Mandatory |
|---|---|---|---|
| geolocation | Geolocation of end user. Format must be lat;lon for example 51.510391;-0.13013. Note: Distance cannot be returned without geolocation. | Latitude and Longitude | Mandatory |
Sent Arguments
| Sent argument | Description | Data type | Optional / Mandatory |
|---|---|---|---|
| n | Limit the number of returned results. Default is 10, System max is 25. | Integer | Optional |
| film_id | The MovieGlu numeric internal film ID | Integer | Mandatory |
| date | The date for which you want to return showtimes, format YYYY-MM-DD | Date | Mandatory |
Caching
The data should not be cached.
Returned data
| Returned Key | Description |
|---|---|
| film | Object – Containing details of requested film |
| film_id | The MovieGlu numeric internal film ID |
| imdb_id (deprecated) | The IMDB film ID (this field will be removed in the next API version) |
| imdb_title_id | The IMDB ID for the film title as used in IMDB URLs in the format tt#######. Recommended use: Concatenate URL “https://www.imdb.com/title/” and “imdb_title_id”, for example https://www.imdb.com/title/tt0076759/ |
| film_name | The film name |
| other_titles | |
| XX | Other titles that may exist, for example in another language XX denotes ISO language code, eg EN, FR or ES |
| version_type | One of the following types: Standard, 3D, IMAX, IMAX3D, Other |
| age_rating | |
| rating | Age rating for film |
| age_rating_image | Age rating image location (where available) |
| age_advisory | Descriptive text accompanying age rating (where available) |
| logo_url | Location of logo image for cinema (generally available for chains 4 or more cinemas, not all countries) |
| film_image | Location of primary image for film |
| film_image_height | Height of image |
| film_image_width | Width of image |
| cinemas | Array – Containing cinema, film and showtime data |
| cinema_id | The MovieGlu numeric internal cinema ID |
| cinema_name | The Cinema name |
| distance | Distance in MILES from user’s geolocation (if provided) |
| showings | Object – containing all showings for this film, regardless of their format. Provided so that if a customer chooses a specific film, we’ll return all viewing options (eg Standard and 3D) for this film. |
| format | Object – name varies according to format type (Standard / 3D / IMAX / 3DIMAX) |
| film_id | The MovieGlu numeric internal film ID |
| film_name | Film name |
| times | Array – A list of showtimes as individual objects (times earlier in the day that have now passed are not returned) |
| start_time | Start time (published start time) in 24hr clock format, eg 19:30 |
| end_time | Estimated end time (Start time + Running Time + 20 mins) in 24hr clock format, eg 22:30 |
Example response
{
"film": {
"film_id": 227902,
"imdb_id": 3829266,
"imdb_title_id": "tt3829266",
"film_name": "The Predator",
"other_titles": {
"EN": "The Predator"
},
"version_type": "Standard",
"age_rating": [
{
"rating": "15 ",
"age_rating_image": "https://d2z9fe5yu2p0av.cloudfront.net/age_rating_logos/uk/15.png",
"age_advisory": "strong bloody violence, sex references, language"
}
],
"film_image": "https://d3ltpb4h29tx4j.cloudfront.net/227902/227902h2.jpg",
"film_image_height": 199,
"film_image_width": 300
},
"cinemas": [
{
"cinema_id": 8922,
"cinema_name": "Vue Cinemas - Shepherds Bush",
"distance": 1.6461926320075,
"logo_url": "https://d2z9fe5yu2p0av.cloudfront.net/chainlogos/uk/UK-712-sq.jpg",
"showings": {
"Standard": {
"film_id": 227902,
"film_name": "The Predator",
"times": [
{
"start_time": "15:45",
"end_time": "17:51"
},
{
"start_time": "16:55",
"end_time": "19:01"
},
{
"start_time": "18:30",
"end_time": "20:36"
},
{
"start_time": "20:00",
"end_time": "22:06"
},
{
"start_time": "22:00",
"end_time": "00:06"
},
{
"start_time": "23:35",
"end_time": "01:41"
}
]
},
"3D": {
"film_id": 277426,
"film_name": "The Predator 3D",
"times": [
{
"start_time": "21:00",
"end_time": "23:06"
}
]
}
}
}
}
],
"status": {
"count": 10,
"state": "OK",
"method": "filmShowTimes",
"message": null,
"request_method": "GET",
"version": "MGv200",
"territory": "UK",
"device_datetime_sent": "2018-09-14T14:31:15.900Z",
"device_datetime_used": "2018-09-14 14:31:15"
}
}