• Register

Future releases

/movies/futureReleases

Returns a list of movies being released in US or Canadian theaters up to 6 months in the future. Release information includes date, type, and distributors.

Response data will be sorted by release date.

Request Parameters

Parameter

Mandatory?

Description

releaseDate Yes Date to start search. Format yyyy-mm-dd.
Can be up to 7 days prior to current date.
numDays No Number of days to search, starting with releaseDate. Maximum search is 180 days.  If not specified, will default to 60 days.
country No USA or CAN. Movies being released in selected country will be returned.  Default is USA.
titleLang No Filter results based on the specified title language. Use IETF language tags (2-letter abbreviations, with optional 2-letter region extensions). If not specified, defaults to 'en'.
descriptionLang No Filter results based on the specified description language. Use IETF language tags (2-letter abbreviations, with optional 2-letter region extensions). If not specified, defaults to 'en'.
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
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.
descLang 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
releases Release metadata, includes the following:
date Date of release for specific country and distributor; formatted yyyy-mm-dd
type Release type (e.g., Original, Limited, Wide, Subsequent)
distributors Release distributor names
country Release country; 3-letter country code
runTime Movie duration, specified in ISO-8601 format; PTxxHyyM = xx hours, yy minutes
entityType Program type (Movie)

Sample Request

http://data.tmsapi.com/v1.1/movies/futureReleases?releaseDate=2015-02-09&numDays=5&api_key=1234567890

Sample Response

[{
    "tmsId": "MV005455480000",
    "rootId": "10498277",
    "subType": "Feature Film",
    "title": "Hits",
    "releaseYear": 2014,
    "releaseDate": "2014-01-21",
    "titleLang": "en",
    "descriptionLang": "en",
    "entityType": "Movie",
    "genres": ["Comedy"],
    "longDescription": "A talentless teen (Meredith Hagner) will do anything to get on TV's \"The Voice.\" Meanwhile, her father (Matt Walsh), a municipal worker, creates an uproar when a video of his rants at City Hall goes viral.",
    "shortDescription": "A teen will do anything to get on \"The Voice,\" while her father's rant at City Hall goes viral.",
    "topCast": ["Meredith Hagner", "Matt Walsh", "James Adomian"],
    "directors": ["David Cross"],
    "advisories": ["Adult Situations"],
    "runTime": "PT01H40M",
    "preferredImage": {
        "uri": "tvbanners/generic/generic_tvbanners_v5.png"
    },
    "releases": [{
        "date": "2015-02-12",
        "country": "USA",
        "type": "Limited",
        "distributors": [{
            "name": "Honora Productions"
        }]
    }]
},]