Movies
Movie showtimes
/movies/
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. 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 |
| 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
Code
Last modified on