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 headerDescriptionData typeOptional / Mandatory
NoneNoneNoneNone

Sent Arguments

Sent argumentDescriptionData typeOptional / Mandatory
cinema_idThe MovieGlu numeric internal cinema IDIntegerMandatory
dateThe date for which you want to return showtimes, format YYYY-MM-DDDateMandatory
film_idThe 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.
IntegerOptional
Sort
Film names ordered by natiowide ‘popularity’ OR ‘alphabetical’
StringOptional

Caching

The returned data can be cached.

Returned data

Returned KeyDescription
cinemaObject – Containing details for requested cinema
cinema_idThe MovieGlu numeric internal cinema ID
cinema_nameThe Cinema name
filmsArray – Containing film and showtime data
film_idThe MovieGlu numeric internal film ID
film_nameThe film name
version_typeOne of the following types: Standard, 3D, IMAX, IMAX3D, Other
age_ratingAge rating for film
film_imageLocation of primary image for film
film_image_heightHeight of image
film_image_widthWidth of image
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_nameThe Film 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
show_datesArray – Dates when film is showing (useful for displaying a date selector for a cinema)
dateList of dates in format yyyy-mm-dd, when showtimes are available at selected cinema

Example response


{
  "cinema": {
    "cinema_id": 10815,
    "cinema_name": "Vue Cinemas - Westwood Cross"
  },
  "films": [
    {
      "film_id": 209869,
      "film_name": "La La Land",
      "version_type": "Standard",
      "age_rating": "12A ",
      "film_image": "https://d3ltpb4h29tx4j.cloudfront.net/209869/209869h2.jpg",
      "film_image_height": 200,
      "film_image_width": 300,
      "showings": {
        "Standard": {
          "film_id": 209869,
          "film_name": "La La Land",
          "times": [
            {
              "start_time": "19:25",
              "end_time": "21:58"
            }
          ]
        }
      },
      "show_dates": [
        {
          "date": "2017-02-08"
        },
        {
          "date": "2017-02-09"
        },
        {
          "date": "2017-02-10"
        },
        {
          "date": "2017-02-11"
        },
        {
          "date": "2017-02-12"
        },
        {
          "date": "2017-02-13"
        },
        {
          "date": "2017-02-14"
        },
        {
          "date": "2017-02-15"
        },
        {
          "date": "2017-02-16"
        }
      ]
    },
    {
      "film_id": 232775,
      "film_name": "T2: Trainspotting 2",
      "version_type": "Standard",
      "age_rating": "18 ",
      "film_image": "https://d3ltpb4h29tx4j.cloudfront.net/232775/232775h2.jpg",
      "film_image_height": 200,
      "film_image_width": 300,
      "showings": {
        "Standard": {
          "film_id": 232775,
          "film_name": "T2: Trainspotting 2",
          "times": [
            {
              "start_time": "17:25",
              "end_time": "19:20"
            },
            {
              "start_time": "20:10",
              "end_time": "22:05"
            },
            {
              "start_time": "22:35",
              "end_time": "00:30"
            }
          ]
        }
      },
      "show_dates": [
        {
          "date": "2017-02-08"
        },
        {
          "date": "2017-02-09"
        },
        {
          "date": "2017-02-10"
        },
        {
          "date": "2017-02-11"
        },
        {
          "date": "2017-02-12"
        },
        {
          "date": "2017-02-13"
        },
        {
          "date": "2017-02-14"
        },
        {
          "date": "2017-02-15"
        },
        {
          "date": "2017-02-16"
        }
      ]
    }
  ],
  "count": 11,
  "status": {
    "state": "OK",
    "code": 1,
    "method": "cinemaShowTimes",
    "message": null,
    "request_method": "GET",
    "version": "MGv101"
  }
}