GET filmShowTimes

Description

Returns showtimes for selected film at all cinemas within 75 miles. 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

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
film_nameThe film name
version_typeOne of the following types: Standard, 3D, IMAX, IMAX3D, Other
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 from user’s geolocation (if provided)
logo_urlLocation of logo image for cinema (generally available for chains 4 or more cinemas)
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": 188115,
    "film_name": "Fantastic Beasts and Where to Find Them",
    "version_type": "Standard",
    "film_image": "https://d3ltpb4h29tx4j.cloudfront.net/188115/188115h2.jpg",
    "film_image_height": 200,
    "film_image_width": 300
  },
  "cinemas": [
    {
      "cinema_id": 8795,
      "cinema_name": "ODEON Leicester Square",
      "distance": 0.026927763381187,
      "logo_url": "https://d2z9fe5yu2p0av.cloudfront.net/chainlogos/uk/UK-614-sq.jpg",
      "showings": {
        "Standard": {
          "film_id": 188115,
          "film_name": "Fantastic Beasts and Where to Find Them",
          "times": [
            {
              "start_time": "17:30",
              "end_time": "20:08"
            },
            {
              "start_time": "20:30",
              "end_time": "23:08"
            }
          ]
        }
      }
    },
    {
      "cinema_id": 29287,
      "cinema_name": "Vue Cinemas - Westfield Stratford City",
      "distance": 5.7239831868778,
      "logo_url": "https://d2z9fe5yu2p0av.cloudfront.net/chainlogos/uk/UK-712-sq.jpg",
      "showings": {
        "Standard": {
          "film_id": 188115,
          "film_name": "Fantastic Beasts and Where to Find Them",
          "times": [
            {
              "start_time": "21:50",
              "end_time": "00:28"
            }
          ]
        }
      }
    }
  ],
  "count": 2,
  "status": {
    "state": "OK",
    "code": 1,
    "method": "filmShowTimes",
    "message": null,
    "request_method": "GET",
    "version": "MGv101"
  }
}