Data/image-api/v1.1/image/videomap

Jump to: navigation, search

Image/VideoMap

Returns the best image for each of up to 25 movies and television programs, as determined by four possible image metadata filters.

Syntax

image/videomap? cosmoid=cosmoid
iguideid=iguideid
&apikey=apikey&sig=sig&formatid=formatid [&imagetypeid=imagetypeid] [&zoomlevel=zoomlevel] [&multi=multi] [&format=format]

Request Example 1

Request a showcard in PNG format for 10 TV series, in a size that fits a bounding box of 120 x 82.

Request Example 2

Request a poster in PNG format for 11 recent movies, in a size that fits a bounding box of 274 x 190.

Request Example 3

Request a key cast image for each of 11 recent movies, in a size that fits a bounding box of 274 x 190.

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.

formatid Yes Image size and file format to be returned. Select the format ID you want from the Format IDs table.

In case an image is unavailable in that format ID, specify multiple IDs in order of preference in a comma-separated list, like this: formatid=36,44,51.

Returned images meet a combination of all of the following specified filters:

  • formatid
  • imagetypeid
  • zoomlevel
cosmoid Conditional Cosmo database ID for a movie, program, episode, or television series. Specify up to 25 IDs in a comma-separated list, like this: cosmoid=7903,22067749,20176744,20503614.

Cosmo is a database of television information. You can grab Cosmo IDs from responses to the following requests:

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

  • cosmoid
  • iguideid
iguideid Conditional An ID for a television program used by the i‑Guide™ interactive digital cable TV program guide. Specify up to 25 IDs in a comma-separated list, like this: iguideid=7072858,4834385,5239665,3899277.

You can get i‑Guide IDs from i‑Guide and from responses to the following requests:

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

  • cosmoid
  • iguideid
format No Format of the returned data: json or xml. The default is JSON.
imagetypeid No Image type of returned images. Select the image type ID you want from the Image Type IDs table.

In case that image type is unavailable, specify multiple IDs in order of preference in a comma-separated list, like this: imagetypeid=6,8

Returned images meet a combination of all of the following specified filters:

  • formatid
  • imagetypeid
  • zoomlevel
multi No How to score images against multiple filters and multiple filter values. Applies to formatid, imagetype, and zoomlevel. Default is balanced.
This value . . .Decrements the score for each value in a list . . .
balancedIn equal proportion to the number of values. For four values, the score decrements by 25 percent. For three, by 33 percent.
fuzzyIn less than equal proportion to the number of values, decreasing the importance of the first value. For four values, the score decrements by less than 25 percent.
targetedIn more than equal proportion to the number of values, increasing the importance of the first value. For four values, the score decrements by more than 25 percent.
diminishedLess for the first parameter in the request and more for the last. For this option, list your parameters in order of importance.
zoomlevel No How close up people in the image appear. Select the zoom level you want from the Image Zoom Level table.

In case an image with that zoom level is unavailable, specify multiple zoom levels in order of preference in a comma-separated list, like this: zoomlevel=1,2,3

Returned images meet a combination of all of the following specified filters:

  • formatid
  • imagetypeid
  • zoomlevel

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.
viewviewSummary of items returned in a list of items.

Response for Image/VideoMap

ResponseTypeDescription
images item [ ] URLs to images that meet the specifications in the request, one for each ID, along with information about each image.

JSON Response Example

Here's the response to a request for up-close cast images for two movies that fit a bounding box of 247 x 131 pixels. 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/image/videomap?apikey=apikey&sig=sig&cosmoid=21364848,
20603751&zoomlevel=1&formatid=88&imagetypeid=6,8
.
{
   "status":"ok",
   "code":200,
   "messages":null,
   "build":"1.0",
   "parameters":{
      "apiKey":"4p1k3y",
      "id":"21364848,20603751",
      "format":"json",
      "formatid":"88",
      "imageTypeId":"6,8"
   },
   "view":{
      "total":2
   },
   "serverName":"tul1cssrcs6.corporate.local",
   "startTime":"2013-12-23T20:42:01Z",
   "endTime":"2013-12-23T20:42:01Z",
   "duration":58,
   "images":[
      {
         "21364848":{
            "url":"http://actual-url-concealed.jpg",
            "caption":"Justin Timberlake, Oscar Isaac",
            "imageCastWeight":1.33,
            "imageTypeId":"6",
            "width":174,
            "height":131,
            "formatid":88,
            "orientation":"Landscape",
            "aspectRatio":"4:3",
            "zoomLevel":1,
            "copyrightOwner":null,
            "author":null
         },
         "20603751":{
            "url":"http://actual-url-concealed.jpg",
            "caption":"Sylvester Stallone",
            "imageCastWeight":1.0,
            "imageTypeId":"6",
            "width":173,
            "height":131,
            "formatid":88,
            "orientation":"Landscape",
            "aspectRatio":"4:3",
            "zoomLevel":1,
            "copyrightOwner":null,
            "author":null
         }
      }
   ]
}

XML Response Example

Here's the response to a request for up-close cast images for two movies that fit a bounding box of 247 x 131 pixels.
Requested with http://api.rovicorp.com/data/v1.1/image/videomap?apikey=apikey&sig=sig&cosmoid=21364848,
20603751&zoomlevel=1&formatid=88&imagetypeid=6,8&format=xml
.
<ImageMap xmlns="com.rovicorp.metadataservice" 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>21364848,20603751</id>
  <format>xml</format>
  <formatid>88</formatid>
  <imageTypeId>6,8</imageTypeId>
</parameters>
<view>
  <total>2</total>
</view>
<serverName>tul1cssrcs4.corporate.local</serverName>
<startTime>2013-12-23T20:44:10Z</startTime>
<endTime>2013-12-23T20:44:10Z</endTime>
<duration>37</duration>
<images>
  <item cosmoid="21364848">
    <image>
      <url>http://actual-url-concealed.jpg</url>
      <caption>Justin Timberlake, Oscar Isaac</caption>
      <imageCastWeight>1.33</imageCastWeight>
      <zoomLevel>1</zoomLevel>
      <imageTypeId>6</imageTypeId>
      <width>174</width>
      <height>131</height>
      <formatid>88</formatid>
      <orientation>Landscape</orientation>
      <aspectRatio>4:3</aspectRatio>
      <copyrightOwner i:nil="true" />
      <author i:nil="true" />
    </image>
  </item>
  <item cosmoid="20603751">
    <image>
      <url>http://actual-url-concealed.jpg</url>
      <caption>Sylvester Stallone</caption>
      <imageCastWeight>1.0</imageCastWeight>
      <zoomLevel>1</zoomLevel>
      <imageTypeId>6</imageTypeId>
      <width>173</width>
      <height>131</height>
      <formatid>88</formatid>
      <orientation>Landscape</orientation>
      <aspectRatio>4:3</aspectRatio>
      <copyrightOwner i:nil="true" />
      <author i:nil="true" />
    </image>
  </item>
</images>
</ImageMap>


See Also

↑ Top

Personal tools