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

Jump to: navigation, search

Image/NameMap

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

Syntax

image/namemap? nameid=nameid
cosmoid=cosmoid
amgpopid=amgpopid
amgmovieid=amgmovieid
amgclassicalid=amgclassicalid		 &apikey=apikey&sig=sig&formatid=formatid [&imagetypeid=imagetypeid] [&zoomlevel=zoomlevel] [&multi=multi] [&format=format]

Request Example 1

Request a celebrity image for each of 7 celebrites in PNG format, in a size that fits a bounding box of 274 x 190 pixels.
http://api.rovicorp.com/data/v1.1/image/namemap?apikey=apikey&sig=sig&nameid=MN0000930642,
MN0000378566,MN0000361272,MN0002293169,MN0001274417,MN0001234247,MN0000031022&imagetypeid=17&
formatid=34

Request Example 2

Request a head-to-chest or head-to-thigh image for each of 7 celebrities, in a size that fits a bounding box of 274 x 190.
http://api.rovicorp.com/data/v1.1/image/videomap?apikey=apikey&sig=sig&cosmoid=134066,101164,
595532,283409,395833,101397,528101&formatid=34&zoomlevel=2

Request Parameters

Sort none.gif  Click to re-sort

Parameter Required Description
apikey Yes Access code that authorizes your request for data from Rovi.
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
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.

amgclassicalid Conditional AMG classical ID for a person who works in movies or television, consisting of a ten-character string that starts with Q and is followed by nine digits with leading spaces. For example: Q   862370. When using an AMG Classical ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: Q+++862370. You can specify up to 25 IDs in a comma-separated list, like this: amgclassicalid=Q+++862370,Q+++103993,Q+++194318.

AMG (All Media Guide) is a database of entertainment information. You can grab AMG classical IDs for people from responses to the following requests:

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

  • nameid
  • cosmoid
  • amgpopidid    
  • amgmovieid
  • amgclassicalid
amgmovieid Conditional AMG movie ID for a person who works in movies or television, consisting of a seven-character string that starts with P and is followed by 6 digits with leading spaces. For example: P 17549. When using an AMG movie ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: P+17549. You can specify up to 25 IDs in a comma-separated list, like this: amgmovieid=P+17549,P+40372,P103436.

AMG (All Media Guide) is a database of entertainment information. You can grab AMG movie IDs for people from responses to the following requests:

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

  • nameid
  • cosmoid
  • amgpopidid    
  • amgmovieid
  • amgclassicalid
amgpopid Conditional AMG pop ID for a person who works in movies or television, consisting of a ten-character string that starts with P and is followed by 9 digits with leading spaces. For example: P   45781. When using an AMG pop ID in a request, replace any spaces in the ID with plus (+) or percent20 (%20) symbols, like this: P+++145781. You can specify up to 25 IDs in a comma-separated list, like this: amgpopid=P+++++4037,P+++145781,P+++172042.

AMG (All Media Guide) is a database of entertainment information. You can grab AMG pop IDs for people from responses to the following requests:

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

  • nameid
  • cosmoid
  • amgpopidid    
  • amgmovieid
  • amgclassicalid
cosmoid Conditional Cosmo database ID for a person who works in movies or television. You can specify up to 25 IDs in a comma-separated list, like this: cosmoid=134066,101164,595532.

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

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

  • nameid
  • cosmoid
  • amgpopidid    
  • amgmovieid
  • amgclassicalid
nameid Conditional Rovi name ID for a person who works in movies or television, consisting of the prefix MN followed by a ten-digit number. For example: MN0000930642. You can specify up to 25 IDs in a comma-separated list, like this: nameid=MN0000930642,MN0000378566,MN0000361272.

You can grab name IDs from responses to Info, Credits, Search, and Recommendations requests. For a complete list of requests that return name IDs, click here.

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

  • nameid
  • cosmoid
  • amgpopidid    
  • amgmovieid
  • amgclassicalid
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.
diminished Less 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/NameMap

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 two celebrity PNGs that fit a bounding box of 247 x 190 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/namemap?apikey=apikey&sig=sig&
nameid=MN0000930642,MN0000378566&imagetypeid=17&formatid=34.
{
   "status":"ok",
   "code":200,
   "messages":null,
   "build":"1.0",
   "parameters":{
      "apiKey":"apikey",
      "id":"MN0000930642,MN0000378566",
      "formatid":"34",
      "imageTypeId":"17"
   },
   "view":{
      "total":2
   },
   "serverName":"tul1cssrcs8.corporate.local",
   "startTime":"2014-01-03T17:26:28Z",
   "endTime":"2014-01-03T17:26:28Z",
   "duration":317,
   "images":[
      {
         "MN0000378566":{
            "url":"http://actual-url-concealed.png",
            "caption":"NEW YORK - APRIL 10: Nathan Lane arrives at the American Theatre Wing Annual Spring Gala at Cipriani 42nd Street on April 10, 2006 in New York City.",
            "imageCastWeight":null,
            "imageTypeId":"17",
            "width":114,
            "height":190,
            "formatid":34,
            "orientation":"Portrait",
            "aspectRatio":"3:5",
            "zoomLevel":3,
            "copyrightOwner":null,
            "author":"Bryan Bedder/Getty Images Entertainment/Getty Images"
         },
         "MN0000930642":{
            "url":"http://actual-url-concealed.png",
            "caption":"LOS ANGELES, CA - FEBRUARY 10: Singer Morris Day (R) and The Time perform onstage during the 50th annual Grammy awards held at the Staples Center on February 10, 2008 in Los Angeles, California.",
            "imageCastWeight":null,
            "imageTypeId":"17",
            "width":142,
            "height":190,
            "formatid":34,
            "orientation":"Portrait",
            "aspectRatio":"3:4",
            "zoomLevel":3,
            "copyrightOwner":null,
            "author":"Kevin Winter/Getty Images Entertainment/Getty Images"
         }
      }
   ]
}

XML Response Example

Here's the XML response to a request for two celebrity PNGs that fit a bounding box of 247 x 190 pixels.
Requested with http://api.rovicorp.com/data/v1.1/image/namemap?apikey=apikey&sig=sig&
nameid=MN0000930642,MN0000378566&imagetypeid=17&formatid=34&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>apikey</apiKey>
    <id>MN0000930642,MN0000378566</id>
    <format>xml</format>
    <formatid>34</formatid>
    <imageTypeId>17</imageTypeId>
  </parameters>
  <view>
    <total>2</total>
  </view>
  <serverName>tul1cssrcs7.corporate.local</serverName>
  <startTime>2014-01-03T17:28:45Z</startTime>
  <endTime>2014-01-03T17:28:46Z</endTime>
  <duration>295</duration>
  <images>
    <item nameid="MN0000378566">
      <image>
        <url>http://actual-url-concealed.png</url>
        <caption>NEW YORK - APRIL 10: Nathan Lane arrives at the American Theatre Wing Annual Spring Gala at Cipriani 42nd Street on April 10, 2006 in New York City.</caption>
        <imageCastWeight i:nil="true" />
        <zoomLevel>3</zoomLevel>
        <imageTypeId>17</imageTypeId>
        <width>114</width>
        <height>190</height>
        <formatid>34</formatid>
        <orientation>Portrait</orientation>
        <aspectRatio>3:5</aspectRatio>
        <copyrightOwner i:nil="true" />
        <author>Bryan Bedder/Getty Images Entertainment/Getty Images</author>
      </image>
    </item>
    <item nameid="MN0000930642">
      <image>
        <url>http://actual-url-concealed.png</url>
        <caption>LOS ANGELES, CA - FEBRUARY 10: Singer Morris Day (R) and The Time perform onstage during the 50th annual Grammy awards held at the Staples Center on February 10, 2008 in Los Angeles, California.</caption>
        <imageCastWeight i:nil="true" />
        <zoomLevel>3</zoomLevel>
        <imageTypeId>17</imageTypeId>
        <width>142</width>
        <height>190</height>
        <formatid>34</formatid>
        <orientation>Portrait</orientation>
        <aspectRatio>3:4</aspectRatio>
        <copyrightOwner i:nil="true" />
        <author>Kevin Winter/Getty Images Entertainment/Getty Images</author>
      </image>
    </item>
  </images>
</ImageMap>


See Also

↑ Top

Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/Data/image-api/v1.1/image/namemap"
Personal tools