Movie showtimes

/movies/:movieId/showings

Returns a list of showtimes for specified movie in local US and Canadian theatres, based on a given geography (zip/postal code or latitude/longitude).

Response data will be sorted by theatre distance and showtime.

Request Parameters

Parameter

Mandatory?

Description

movieId Yes tmsId or rootId of movie
startDate Yes Start date, formatted yyyy-mm-dd.
Current date or greater.
numDays No Number of days for which to return showtimes. Theatres generally release showtimes by week, Fri-Thurs. Some advance ticket showtimes for major releases may be available up to 90 days in advance.
Default is 1. Value must be between 1 and 90.

zip

No

Postal code (US or Canadian)
Must supply either zip/postal code or coordinates.
lat No Latitude; valid values are between -90 and 90.
Must supply either zip/postal code or coordinates.
lng No Longitude; valid values are between -180 and 180.
Must supply either zip/postal code or coordinates.
radius No Range to search from initial location. Maximum is 100 mi (160 km).
Defaults to 5.
units No Unit of measurement for radius parameter. Valid values are mi or km. Defaults to miles.
Also specifies unit of measurement for distance field in response.
imageSize No Requested size of image returned in preferredImage URI.
Valid values are: Sm, Md, Lg, Ms. See Image Sizing for details.
If not specified, defaults to Md.
If requested image size is not available, generic image will be returned.

imageText

No

Boolean indicating preference for image types with text (banners) or without text (iconics). If requested preference is not available, image selection will continue to next type (banner/iconic), before finally returning generic if no image found. Defaults to true for text preference.

api_key

Yes

24-character key obtained during application registration

Response Body

Response

Description

tmsId Resource identifier for movie
rootId Numeric resource identifier for program; parent id for all program variations in languages and versions
title Movie title, as set for release
titleLang 2-letter language abbreviation code (e.g., 'en'=English, 'sp'=Spanish)
shortDescription Movie description, maximum 100 characters.
descriptionLang 2-letter language abbreviation code (e.g., 'en'=English, 'sp'=Spanish)
ratings Ratings metadata, if available
body Ratings body; currently returning only MPAA ratings for movies
code Ratings code (e.g., G, PG, PG-13)
genres Comma-separated list of movie genres (e.g., Romance, Horror, Comedy)
topCast Comma-separated list of top 3 cast member names, if available.
preferredImage Movie image, if available; see Image Metadata for details
releaseYear Original year of release, regardless of release country
qualityRating Critial ratings metadata, if available.
ratingsBody Critial reviewer; currently returning only TMS quality ratings
value Number of stars (for TMS ratings, 1-4 stars)
officialUrl Official movie website, if available
runTime Movie duration, specified in ISO-8601 format; PTxxHyyM = xx hours, yy minutes
showtimes List of showtimes objects with the following elements:
theatre Theatre object with the following elements:
id Resource identifier for theatre
name Theatre name
barg Boolean indicating bargain or matinee pricing for showtime
dateTime Movie showtime, in the theater’s local time zone.
ticketURI For Fandango-affiliated theatres, partial link to online Fandango ticketing.
A Fandango affiliate agreement is needed for full use of online ticketing. TMS Sales representatives can provide additional information on this service.
quals Also referred to as 'General Settings' by theatres. These are attributes or services specific to the screen or auditorium where a title is playing for the given showtime.
Examples are No Passes, Stadium Seating, Digital Presentation. Multiple values are delimited by '|'.
entityType Program type (Movie)

Sample Request

http://data.tmsapi.com/v1.1/movies/9128357/showings?startDate=2012-12-08&api_key=1234567890

Sample Response

[
  {
    "tmsId": "MV003903970000",
    "rootId": "9128357",
    "title": "Argo",
    "titleLang": "en",
    "shortDescription": "A CIA agent hatches a risky plan to get six Americans out of Tehran during the Iran hostage crisis.",
    "descriptionLang": "en",
    "ratings": [ { "body": "Motion Picture Association of America",  "code": "R" } ],
    "genres": ["Historical drama", "Thriller"],
    "topCast": ["Ben Affleck", "Bryan Cranston", "Alan Arkin" ],
    "preferredImage": {
      "uri": "movieposters/v5/AllPhotos/9128357/p9128357_p_v5_aa.jpg",
      "height": "360",
      "width": "240",
      "primary": "true",
      "category": "Poster Art",
      "caption": { "content": "Argo (2012)", "lang": "en" }
    },
    "releaseYear": 2012,
    "qualityRating": { "ratingsBody": "TMS", "value": "3.5" },
    "officialUrl": "http://argothemovie.warnerbros.com/",
    "runTime": "PT02H00M",
    "showtimes": [
      {
        "theatre": {"id": "5936", "name": "Regal City North Stadium 14"},
        "barg": false,
        "dateTime": "2012-12-08T19:05",
      },
      {
        "theatre": {"id": "5936", "name": "Regal City North Stadium 14"},
        "barg": false,
        "dateTime": "2012-12-08T22:05",
      }
    ],
    "entityType": "Movie"
  }
]