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"
  }
]