Data/movie-api/v1.1/movie-release/info

Jump to: navigation, search

MovieRelease/Info

Returns basic information about a movie release plus customized requests for all of the other Movie Release content that is available. These customized requests are designed to make your programming easy and efficient: in a single step you both verify availability of the data and capture the request. You just add your sig parameter and execute the request.

The movierelease/info request also provides an optional argument to include responses from any or all of the other MovieRelease requests. This may return a large amount of data. To speed data transmission, do the following:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.

Syntax

movierelease/info? upcid=upcid
moviereleaseid=moviereleaseid
&apikey=apikey&sig=sig [&include=include] [&format=format] [&country=country] [&language=language] [&formatid=formatid] [&imagecount=imagecount] [&imageoffset=imageoffset] [&imagesize=imagesize] [&imagesort=imagesort]

Request Example 1

Request information about the extended collector's edition of Avatar using the movie release ID.

Request Example 2

Request information using the UPC code of the DVD.

Request Example 3

Include images that are in the range of 70 to 100 pixels in both dimensions.

Request Example 4

Include JPGs that are 100 pixels in one or both dimensions.

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikey Yes Access code that authorizes your request for data from Rovi.
sig Yes A calculated, 32-hex-digit authorization code. To perform the calculation, execute the MD5 function on the concatenation of the following three ASCII strings:
  • Your API key.
  • The secret key you received with your API key.
  • The Unix time. Unix time is a timestamp supported in most development environments, and is generally defined as the number of seconds since January 1, 1970 00:00:00 GMT.

Express the alpha hex digits as lower case.

Perform the calculation at the time of each request to be sure it's within a five-minute window of the server time. If you're testing the call in a browser, use our online signature generator to perform the calculation.

moviereleaseid Conditional ID of a movie release. Your application can grab movie release IDs from Movie/Releases responses.

Condition: The request must contain just one of these parameters:

  • upcId
  • movieReleaseId
upcid Conditional The numbers from the Universal Product Code (UPC) barcode that identifies an item.

Condition: The request must contain just one of these parameters:

  • upcId
  • movieReleaseId
country No Country the language parameter applies to. The current release of the API supports only US.
format No Format of the returned data: json or xml. The default is JSON.
formatid No If you specify All or Images in the include parameter, formatid specifies the size and file format of returned images. Select the format IDs you want from the Format IDs table.

Specify multiple format IDs in a comma-separated list, like this: formatid=36,44,51.

If you also specify imagesize, returned images meet a combination of one formatid and one imagesize filter. Note: Your access to images is governed by your subscription level.

imagecount No If you specify All or Images in the include parameter, imagecount specifies the number of images to be returned. If fewer images are available, the available images are returned without error. The default is 25.

Use imagecount and imageoffset to paginate images in the response.
Note:  Your access to images is governed by your subscription level.

imageoffset No If you specify All or Images in the include parameter, imageoffset specifies the number of images at the start of the response to skip. The default is zero.

Use imagecount and imageoffset to paginate images in the response.
Note:  Your access to images is governed by your subscription level.

imagesize No If you specify All or Images in the include parameter, imagesize specifies the image sizes to be returned. Images are not dynamically resized to fit, so only available sizes are returned.
  • Specify an exact size in width x height format, like this: imagesize=332x419.
  • Specify a size range in width x height format, like this: imagesize=60-80x80-100.
  • Specify multiple sizes in a comma-separated list, like this: imagesize=332x419,60-80x80-100.

If you also specify formatid, returned images meet a combination of one formatid and one imagesize filter. Note:  Your access to images is governed by your subscription level.

imagesort No If you specify All or Images in the include parameter, imagesort specifies the sort order of returned images. Images can be sorted in ascending or descending order by the following properties:
  • width
Image width.
  • height
Image height.
  • formatid
Image format ID, as shown in the Format IDs table.
  • author
Person or company that took the photo.
  • copyrightowner  
Company that owns the image copyright.
  • url
URL to the image (ASCII sort).

Specify a descending sort order with a minus (-) sign, like this: imagesort=-width.
Specify a multilevel sort in highest-to-lowest order in a comma-separated list, like this: imagesort=formatid,-height,width.

Note:  Your access to images is governed by your subscription level.

multi and imagesort cannot be used in the same request, only one or the other is permitted

include No Any other Movie Release requests to include in the request. For example, to include the description, add &include=description.

You can specify multiple includes in either of the following ways:

  • In multiple arguments, like this: include=images&include=videos.
  • In a single argument as a comma-separated list, like this: include=images,videos.

You can also include all Movie Release requests with include=all. The possible values are:

For information about a request, please see the documentation for the request.

Reminder: These options may return a large amount of data. To speed data transmission, do the following:

  • Request only data that you need to immediately display.
  • Request a compressed response by including Accept-Encoding: gzip,deflate in the HTTP header.
language No Language of the response data. This request supports only en (English).

Response

Response Header

ResponseTypeDescription
buildstringThe software release level of the API.
codeintegerHTTP status code. See the status field for the text part of the code.
durationintegerServer processing time in milliseconds. The difference between startTime and endTime.
endTimestringWhen the server sent the response (UTC time).
messagesMessage [ ]Elements of a multiple HTTP response status message.
parametersparametersThe parameters that were included in the request.
serverNamestringName of the server that processed the request.
startTimestringWhen the server received the request (UTC time).
statusstringText part of the HTTP status code, which is shown in the code field.

Response for MovieRelease/Info

ResponseTypeDescription
aspect string Video display aspect ratio used by the release.
chapters string [ ] Chapters of the movie in the movie release, returned only if the request specified an include=chapters argument.
chaptersUri string The customized MovieRelease/Chapters request, returned only if chapters data is available.
collection collection Links to information about the movies, series, seasons, and episodes included in a collection on a release, returned only if the request specified an include=collection argument.
collectionUri string The customized MovieRelease/Collection request, returned only if the data is available.
description description Description of the release, returned only if the request specified an include=description argument.
descriptionUri string The customized MovieRelease/Description request, returned only if a description is available.
directors Director [ ] Directors of the movie or TV series, listed alphabetically in order of last name.
featureRating integer MPAA rating of the movie.
features string [ ] Special features included on a release, returned only if the request specified an include=features argument. Features include trailers, interviews, commentaries, etc.
featuresUri string The customized MovieRelease/Features request, returned only if a list of features is available.
formats string [ ] Media and formats used for the release.
genres Genre [ ] Genres that apply to the movie, along with a weighting that reflects the relative importance of each genre.

Genres are sorted in order of importance (highest to lowest weight) and, within the same weight, alphabetically by genre name.

ids ids All of the IDs associated with the release that are recognized by the API. The possible IDs are:
  • upcId
  • releaseId
  • movieReleaseId
images Image [ ] URLs to images of the release, along with the size of each image. Returned only if the request specified an include=images argument and your subscription level enables access to images.
imagesUri string The customized MovieRelease/Images request, returned only if images are available.
languages string [ ] Language soundtracks that are available for the movie on the release.
movieId string Movie ID of the movie on the release.
programType string Type of program:
  • Movie
  • Series
  • Season
  • Episode
  • One Time Only
  • Unknown
rating integer An editorially assigned rating of the movie from 0 to 9, where 0 is no rating and higher numbers indicate a higher rating.
region integer DVD region code of the release.
releaseDate string Date the movie release was released in YYYY-MM-DD order.
requestedId string The ID in the request that applies to this response object.
screenFormat string Video display technology used by the release to accommodate the aspect ratio.
sides integer Number of DVD sides used on the release.
sound string Audio technology used by the release.
studio string The company that distributed the release.
subtitles string [ ] Languages of the subtitles available on the release.
title string Title of the release.
videos Video [ ] Data for constructing links to trailers for the movie release, returned only if the request specified an include=videos argument.
videosUri string The customized MovieRelease/Videos request, returned only if data is available.

JSON Response Example

Here's the response to Request Example 1, which asks for information about the extended collector's edition of Avatar. The response is formatted with extra spaces and carriage returns to make it easy to read.
Requested with http://api.rovicorp.com/data/v1.1/movierelease/info?apikey=apikey&sig=sig&
moviereleaseid=E247882
.
{
   "status":"ok",
   "code":200,
   "messages":null,
   "build":"1.0",
   "parameters":{
      "apiKey":"4p1k3y",
      "id":"E247882",
      "format":"json"
   },
   "serverName":"tul1cssrcs8.corporate.local",
   "startTime":"2015-05-18T16:37:09Z",
   "endTime":"2015-05-18T16:37:09Z",
   "duration":8,
   "release":{
      "ids":{
         "movieReleaseId":"E247882",
         "releaseId":"E247882",
         "upcId":"024543713678"
      },
      "movieId":"V 352199",
      "title":"Avatar [Extended Collector's Edition] [3 Discs]",
      "programType":"Movie",
      "rating":6,
      "featureRating":0,
      "directors":[
         {
            "id":"P 10397",
            "name":"James Cameron"
         }
      ],
      "genres":[
         {
            "id":"D 652",
            "name":"Science Fiction",
            "weight":5
         }
      ],
      "formats":[
         "DVD"
      ],
      "releaseDate":"2010 11 16",
      "languages":[
         "English",
         "French",
         "Spanish"
      ],
      "subtitles":[
         "Spanish"
      ],
      "screenFormat":"WSE",
      "sound":"DD5.1/DS",
      "aspect":"1.78:1",
      "region":1,
      "sides":3,
      "description":null,
      "descriptionUri":null,
      "features":null,
      "featuresUri":"http://api.rovicorp.com/data/v1.1/movierelease/features?format=json&apikey=4p1k3y&moviereleaseid=E247882",
      "images":null,
      "imagesUri":"http://api.rovicorp.com/data/v1.1/movierelease/images?format=json&apikey=4p1k3y&moviereleaseid=E247882",
      "videos":null,
      "videosUri":"http://api.rovicorp.com/data/v1.1/movierelease/videos?format=json&apikey=4p1k3y&moviereleaseid=E247882",
      "studio":"20th Century Fox",
      "chapters":null,
      "chaptersUri":"http://api.rovicorp.com/data/v1.1/movierelease/chapters?format=json&apikey=4p1k3y&moviereleaseid=E247882",
      "collection":null,
      "collectionUri":"http://api.rovicorp.com/data/v1.1/movierelease/collection?format=json&apikey=4p1k3y&moviereleaseid=E247882",
      "requestedId":null
   }
}

XML Response Example

Here's an XML response to Request Example 1, which asks for information about the extended collector's edition of Avatar. The response is formatted with extra spaces and carriage returns to make it easy to read.
Requested with http://api.rovicorp.com/data/v1.1/movierelease/info?apikey=apikey&sig=sig&
moviereleaseid=E247882&format=xml
.
<MovieReleaseDetail
   xmlns="com.rovicorp.metadataservice"
   xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
   xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true" />
    <build>1.0</build>
    <parameters>
        <apiKey>4p1k3y</apiKey>
        <id>E247882</id>
        <format>xml</format>
    </parameters>
    <serverName>tul1cssrcs6.corporate.local</serverName>
    <startTime>2015-05-18T16:39:13Z</startTime>
    <endTime>2015-05-18T16:39:13Z</endTime>
    <duration>6</duration>
    <release>
        <ids>
            <movieReleaseId>E247882</movieReleaseId>
            <releaseId>E247882</releaseId>
            <upcId>024543713678</upcId>
        </ids>
        <movieId>V 352199</movieId>
        <title>Avatar [Extended Collector's Edition] [3 Discs]</title>
        <programType>Movie</programType>
        <rating>6</rating>
        <featureRating>0</featureRating>
        <directors>
            <Director>
                <id>P 10397</id>
                <name>James Cameron</name>
            </Director>
        </directors>
        <genres>
            <Genre>
                <id>D 652</id>
                <name>Science Fiction</name>
                <weight>5</weight>
            </Genre>
        </genres>
        <formats>
            <a:string>DVD</a:string>
        </formats>
        <releaseDate>2010 11 16</releaseDate>
        <languages>
            <a:string>English</a:string>
            <a:string>French</a:string>
            <a:string>Spanish</a:string>
        </languages>
        <subtitles>
            <a:string>Spanish</a:string>
        </subtitles>
        <screenFormat>WSE</screenFormat>
        <sound>DD5.1/DS</sound>
        <aspect>1.78:1</aspect>
        <region>1</region>
        <sides>3</sides>
        <description i:nil="true" />
        <descriptionUri i:nil="true" />
        <features i:nil="true" />
        <featuresUri>http://api.rovicorp.com/data/v1.1/movierelease/features?format=xml&apikey=4p1k3y&moviereleaseid=E247882</featuresUri>
        <images i:nil="true" />
        <imagesUri>http://api.rovicorp.com/data/v1.1/movierelease/images?format=xml&apikey=4p1k3y&moviereleaseid=E247882</imagesUri>
        <videos i:nil="true" />
        <videosUri>http://api.rovicorp.com/data/v1.1/movierelease/videos?format=xml&apikey=4p1k3y&moviereleaseid=E247882</videosUri>
        <studio>20th Century Fox</studio>
        <chapters i:nil="true" />
        <chaptersUri>http://api.rovicorp.com/data/v1.1/movierelease/chapters?format=xml&apikey=4p1k3y&moviereleaseid=E247882</chaptersUri>
        <collection i:nil="true" />
        <collectionUri>http://api.rovicorp.com/data/v1.1/movierelease/collection?format=xml&apikey=4p1k3y&moviereleaseid=E247882</collectionUri>
        <requestedId i:nil="true" />
    </release>
</MovieReleaseDetail>


See Also

↑ Top

Personal tools