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 headerDescriptionData typeOptional / Mandatory
geolocationGeolocation of end user. Format must be lat;lon for example 51.510391;-0.13013. Note: Distance cannot be returned without geolocation.Latitude and LongitudeMandatory

Sent Arguments

Sent argumentDescriptionData typeOptional / Mandatory
nLimit the number of returned results. Default is 10, System max is 25.IntegerOptional
film_idThe MovieGlu numeric internal film IDIntegerMandatory
dateThe date for which you want to return showtimes, format YYYY-MM-DDDateMandatory

Caching

The data should not be cached.

Returned data

Returned KeyDescription
filmObject – Containing details of requested film
film_idThe MovieGlu numeric internal film ID
imdb_id (deprecated)The IMDB film ID (this field will be removed in the next API version)
imdb_title_idThe 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_nameThe film name
other_titles
XXOther titles that may exist, for example in another language
XX denotes ISO language code, eg EN, FR or ES
version_typeOne of the following types: Standard, 3D, IMAX, IMAX3D, Other
age_rating
ratingAge rating for film
age_rating_imageAge rating image location (where available)
age_advisoryDescriptive text accompanying age rating (where available)
logo_urlLocation of logo image for cinema (generally available for chains 4 or more cinemas, not all countries)
film_imageLocation of primary image for film
film_image_heightHeight of image
film_image_widthWidth of image
cinemasArray – Containing cinema, film and showtime data
cinema_idThe MovieGlu numeric internal cinema ID
cinema_nameThe Cinema name
distanceDistance in MILES from user’s geolocation (if provided)
showingsObject – 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.
formatObject – name varies according to format type (Standard / 3D / IMAX / 3DIMAX)
film_idThe MovieGlu numeric internal film ID
film_nameFilm name
timesArray – A list of showtimes as individual objects (times earlier in the day that have now passed are not returned)
start_timeStart time (published start time) in 24hr clock format, eg 19:30
end_timeEstimated 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"
  }
}