Method name
- Quick start guide
- Troubleshooting
- Headers and Responses
- Sample code
- GET filmsNowShowing
- GET filmsComingSoon
- GET filmLiveSearch
- GET cinemaLiveSearch
- GET filmDetails
- GET cinemaDetails
- GET cinemasNearby
- GET cinemaShowTimes
- GET filmShowTimes
- GET closestShowing
- GET purchaseConfirmation
- GET images
- GET trailers
GET cinemaShowTimes
Description
Returns showtimes based on combination of cinema, date and film. Results can be sorted by popularity or alphabetically.
Scenario 1
Sent: Cinema ID, Film ID, Date
Returned: Showtimes for specified cinema, film and date combination
Scenario 2
Sent: Cinema ID and Date only
Returned: Showtimes for ALL films at specified cinema, on specified date
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
cinemaShowTimes/?film_id=12345&cinema_id=54321&date=2018-04-12&sort=popularity
Required headers
| Sent header | Description | Data type | Optional / Mandatory |
|---|---|---|---|
| None | None | None | None |
Sent Arguments
| Sent argument | Description | Data type | Optional / Mandatory |
|---|---|---|---|
| cinema_id | The MovieGlu numeric internal cinema ID | Integer | Mandatory |
| date | The date for which you want to return showtimes, format YYYY-MM-DD | Date | Mandatory |
| film_id | The MovieGlu numeric internal film ID. Inclusion of a film ID in the query will return showtimes for only that cinema, film and date combination. If not sent, then response will return Showtimes for ALL films at specified cinema, on specified date. | Integer | Optional |
| Sort | Film names ordered by natiowide ‘popularity’ OR ‘alphabetical’ | String | Optional |
Caching
The returned data can be cached.
Returned data
| Returned Key | Description |
|---|---|
| cinema | Object – Containing details for requested cinema |
| cinema_id | The MovieGlu numeric internal cinema ID |
| cinema_name | The Cinema name |
| films | Array – Containing film and showtime data |
| 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 | Other titles that may exist, for example in another language, preceeded by the ISO language, eg EN, FR or ES |
| 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) |
| film_image | Location of primary image for film |
| film_image_height | Height of image |
| film_image_width | Width of image |
| 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 | The 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 |
| show_dates | Array – Dates when film is showing (useful for displaying a date selector for a cinema) |
| date | List of dates in format yyyy-mm-dd, when showtimes are available at selected cinema |
Example response
{
"cinema": {
"cinema_id": 8941,
"cinema_name": "Vue Cinemas - Reading"
},
"films": [
{
"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,
"showings": {
"Standard": {
"film_id": 227902,
"film_name": "The Predator",
"times": [
{
"start_time": "14:30",
"end_time": "16:36"
},
{
"start_time": "15:45",
"end_time": "17:51"
},
{
"start_time": "17:05",
"end_time": "19:11"
},
{
"start_time": "18:30",
"end_time": "20:36"
},
{
"start_time": "20:00",
"end_time": "22:06"
},
{
"start_time": "21:10",
"end_time": "23:16"
},
{
"start_time": "22:00",
"end_time": "00:06"
},
{
"start_time": "23:05",
"end_time": "01:11"
}
]
}
},
"show_dates": [
{
"date": "2018-09-14"
},
{
"date": "2018-09-15"
},
{
"date": "2018-09-16"
},
{
"date": "2018-09-17"
},
{
"date": "2018-09-18"
},
{
"date": "2018-09-19"
},
{
"date": "2018-09-20"
}
]
}
}
],
"status": {
"count": 13,
"state": "OK",
"method": "cinemaShowTimes",
"message": null,
"request_method": "GET",
"version": "MGv200",
"territory": "UK",
"device_datetime_sent": "2018-09-14T14:13:40.375Z",
"device_datetime_used": "2018-09-14 14:13:40"
}
}