Catalog-matching-api/v2.1/match/video

Jump to: navigation, search

Match/Video

Returns Rovi IDs for a movie, TV series, or TV program in your catalog, based on title and field-level data, along with data you can use to verify a match. Results are returned in order of confidence level.

Note: The primary Rovi IDs you should track are:

For This API . . .Use this ID.
Rovi VideocosmoId.
Rovi TV Listings  cosmoId.
Rovi DVDsmovieId, also known as amgMovieId.

Syntax

catalog/match/video?apikey=apikey&sig=sig&title=title [&entitytype=entitytype] [&rating=rating] [&releaseyear=releaseyear] [&runtime=runtime] [&upc=upc] [&include=include] [&formatid=formatid] [&format=format] [&size=size]

Request Example 1

Get IDs for the Star Trek series that started in 1995 and include cast members for verification.

Request Example 2

Get IDs for movies titled House of Numbers and include a synopsis for verification.

Request Example 3

Get IDs for the latest Star Trek movie by a UPC code and include a list of DVD releases in an XML response.

Request Parameters

  Movie-related requests    ⊑⊒  TV-related requests

ParameterRequiredDescription
apikey Yes Access code that authorizes your request for data from Rovi.
catalog Yes Database to match against.
To match against . . .Specify this catalog.
movies and TV series (our DVD database)amgvideo 
television (our international TV schedule database)video ⊑⊒
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.

title Yes Title of a movie, television program, or television series, or keywords from the title. This searches for the most popular title with that combination of words. Replace any spaces with plus (+) or percent20 (%20) symbols.

Note: This parameter currently returns only US-English results. Support for other countries and languages will be added in the future.

entitytype No Categories that narrow the type of content to match against. Select one of the following entity types:
In this catalog . . .   To match against . . .   Specify this entitytype.
amgvideo moviesmovie
TV seriestvseries
video ⊑⊒moviesmovie
TV seriestvseries
TV programsonetimeonly

The default is to match against all entity types for a catalog. Note:  The top results may come from just one of the entity types. Order of results is determined by relevance and is not deliberately balanced across the entity types.

format No Format of the returned data: json or xml. The default is JSON.

Alternatively you can specify the response format in an HTTP Accept header with either of these Accept field content types:

  • application/xml
  • application/json

If you specify both, the format parameter overrides the Accept header.

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.

include No Additional data to include in each result returned. To include cast members in movie results, for example, specify include=cast. For multiple includes, separate the values with commas like this: include=moods,crew. To include all data, specify include=all.
For this catalog. . .You can include these results . . .
amgvideo 
video ⊑⊒
rating No MPAA movie rating or US TV rating. Ratings with a dash may be entered with or without the dash.
US TV RatingMPAA Rating
  • None
  • NR
  • TV-Y
  • G
  • TV-Y7
  • PG
  • TV-G
  • PG-13
  • TV-PG
  • R
  • TV-14
  • NC-17
  • TV-MA
  • X
releaseyear No Year the title was released.
runtime No Length of the title in minutes.
size No The number of items you want to be returned. The default is 20.
upc No Universal Product Code (UPC) for the item. Available only for a catalog of amgvideo.

Response

Response Header

ResponseTypeDescription
controlSet ControlSet The HTTP response status.
id String Server transaction ID for the response.

Response for Match/Video

ResponseTypeDescription
results result [ ] Information about items that match the criteria specified in the request.

Response Example 1

Here's the response to Request Example 1, looking for IDs for the Star Trek series that started in 1995 and including cast members in the response. Just the top result is requested here to show as a sample.
Requested with http://api.rovicorp.com/recognition/v2.1/video/match/video?apikey=apikey&sig=sig&
title=star+trek&entitytype=tvseries&releaseyear=1995&include=awards&size=1
.
{
   "matchResponse":{
      "meta:id":"tul1cpgtsrapp1:gwy:xz1t",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"tvseries",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.5397823
               }
            ],
            "id":857974,
            "messages":null,
            "video":{
               "ids":{
                  "amgMovieId":null,
                  "cosmoId":"857974",
                  "iguideId":857974
               },
               "seriesIds":null,
               "masterTitle":"Star Trek: Voyager",
               "secondaryTitle":"",
               "episodeTitle":null,
               "category":"Other",
               "color":"Color",
               "lastAirDate":"2001-05-23T00:00:00Z",
               "originalAirDate":"1995-01-16T00:00:00Z",
               "programType":"Series",
               "releaseYear":1995,
               "duration":60,
               "subcategory":"sci-fi",
               "syndicated":true,
               "programLanguage":"English",
               "partNumber":null,
               "partTotal":null,
               "parentalRatings":null,
               "parentalRatingsUri":"http://api.rovicorp.com/v1/video/parentalratings?format=json&apikey=141341&cosmoid=857974",
               "cast":[
                  {
                     "name":"Kate Mulgrew",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=308836",
                     "role":"Actor",
                     "isCelebrity":true,
                     "isOrganization":false,
                     "partName":"Capt. Kathryn Janeway",
                     "sequence":1,
                     "image":{
                        "height":250,
                        "width":187,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":null,
                        "copyrightOwner":"Andrew H. Walker/Getty Images Entertainment/Getty Images"
                     }
                  },
                  {
                     "name":"Robert Beltran",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=410852",
                     "role":"Actor",
                     "isCelebrity":false,
                     "isOrganization":false,
                     "partName":"First Off. Chakotay",
                     "sequence":2,
                     "image":{
                        "height":250,
                        "width":197,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":null,
                        "copyrightOwner":"Getty Images/Getty Images Entertainment/Getty Images"
                     }
                  },
                  {
                     "name":"Tim Russ",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=453396",
                     "role":"Actor",
                     "isCelebrity":true,
                     "isOrganization":false,
                     "partName":"Security Chief Tuvok",
                     "sequence":3,
                     "image":{
                        "height":250,
                        "width":177,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":null,
                        "copyrightOwner":"David Livingston/Getty Images Entertainment/Getty Images"
                     }
                  },
                  {
                     "name":"Ethan Phillips",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=126194",
                     "role":"Actor",
                     "isCelebrity":false,
                     "isOrganization":false,
                     "partName":"Neelix",
                     "sequence":4,
                     "image":{
                        "height":166,
                        "width":250,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":"Mitch Haddad/ABC",
                        "copyrightOwner":null
                     }
                  },
                  {
                     "name":"Robert Picardo",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=518042",
                     "role":"Actor",
                     "isCelebrity":true,
                     "isOrganization":false,
                     "partName":"The Doctor",
                     "sequence":5,
                     "image":{
                        "height":250,
                        "width":162,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":null,
                        "copyrightOwner":"David Livingston/Getty Images Entertainment/Getty Images"
                     }
                  },
                  {
                     "name":"Roxann Dawson",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=315576",
                     "role":"Actor",
                     "isCelebrity":false,
                     "isOrganization":false,
                     "partName":"Chief Engineer B'Elanna Torres",
                     "sequence":6,
                     "image":null
                  },
                  {
                     "name":"Robert Duncan McNeill",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=605032",
                     "role":"Actor",
                     "isCelebrity":false,
                     "isOrganization":false,
                     "partName":"Lt. Tom Paris",
                     "sequence":7,
                     "image":null
                  },
                  {
                     "name":"Garrett Wang",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=285618",
                     "role":"Actor",
                     "isCelebrity":false,
                     "isOrganization":false,
                     "partName":"Ens. Harry Kim",
                     "sequence":8,
                     "image":null
                  },
                  {
                     "name":"Jennifer Lien",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=454641",
                     "role":"Actor",
                     "isCelebrity":false,
                     "isOrganization":false,
                     "partName":"Kes",
                     "sequence":9,
                     "image":{
                        "height":187,
                        "width":250,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":"Warner Brothers",
                        "copyrightOwner":null
                     }
                  },
                  {
                     "name":"Jeri Ryan",
                     "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=101833",
                     "role":"Actor",
                     "isCelebrity":true,
                     "isOrganization":false,
                     "partName":"Seven of Nine",
                     "sequence":10,
                     "image":{
                        "height":250,
                        "width":176,
                        "formatid":44,
                        "url":"http://actual-url-concealed.jpg",
                        "author":null,
                        "copyrightOwner":"Alberto Rodriguez/Getty Images Entertainment/Getty Images"
                     }
                  }
               ],
               "castUri":"http://api.rovicorp.com/v1/video/cast?format=json&apikey=141341&cosmoid=857974",
               "crew":null,
               "crewUri":"http://api.rovicorp.com/v1/video/crew?format=json&apikey=141341&cosmoid=857974",
               "awards":null,
               "awardsUri":"http://api.rovicorp.com/v1/video/awards?format=json&apikey=141341&cosmoid=857974",
               "images":null,
               "imagesUri":"http://api.rovicorp.com/v1/video/images?format=json&apikey=141341&cosmoid=857974",
               "clip":null,
               "clipUri":null,
               "seasons":null,
               "seasonsUri":"http://api.rovicorp.com/v1/video/seasons?format=json&apikey=141341&cosmoid=857974",
               "variants":null,
               "variantsUri":"http://api.rovicorp.com/v1/video/variants?format=json&apikey=141341&cosmoid=857974",
               "schedule":"",
               "scheduleUri":null,
               "event":null,
               "eventUri":null,
               "keywords":null,
               "keywordsUri":null,
               "moods":null,
               "moodsUri":"http://api.rovicorp.com/v1/video/moods?format=json&apikey=141341&cosmoid=857974",
               "related":null,
               "relatedUri":"http://api.rovicorp.com/v1/video/related?format=json&apikey=141341&cosmoid=857974",
               "review":null,
               "reviewUri":null,
               "synopsis":null,
               "synopsisUri":"http://api.rovicorp.com/v1/video/synopsis?format=json&apikey=141341&cosmoid=857974",
               "themes":null,
               "themesUri":"http://api.rovicorp.com/v1/video/themes?format=json&apikey=141341&cosmoid=857974",
               "tones":null,
               "tonesUri":null
            }
         }
      ]
   }
}

Response Example 2

Here's the response to Request Example 2, looking for IDs for the latest Star Trek movie by a UPC code and requesting a list of DVD releases in an XML response. Just the top result is requested here to show as a sample.
Requested with http://api.rovicorp.com/recognition/v2.1/amgvideo/match/video?apikey=apikey&sig=sig&
title=star+trek&entitytype=movie&upc=097363485049&include=releases&format=xml&size=1
.
<sortResponse xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:meta="com.rovicorp.metadataservice" xmlns="com.rovicorp.metadataservice" meta:id="tul1cpgtsrapp1:gwy:xzaw">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true"/>
  </controlSet>
  <results>
    <result>
      <type>movie</type>
      <relevance>
        <code>Score</code>
        <value>0.65</value>
      </relevance>
      <availabilties/>
      <id>V 356492</id>
      <messages i:nil="true"/>
      <movie>
        <ids>
          <cosmoId>8904813</cosmoId>
          <movieId>V 356492</movieId>
        </ids>
        <title>Star Trek</title>
        <releaseYear>2009</releaseYear>
        <rating>7</rating>
        <duration>126</duration>
        <directors>
          <Director>
            <id>P240910</id>
            <name>J.J. Abrams</name>
          </Director>
        </directors>
        <countries>
          <a:string>USA</a:string>
        </countries>
        <mpaa>PG13</mpaa>
        <flags>
          <a:string>Sexual Situations</a:string>
          <a:string>Sci-Fi Violence</a:string>
        </flags>
        <genres>
          <Genre>
            <id>D 652</id>
            <name>Science Fiction</name>
            <weight>5</weight>
          </Genre>
        </genres>
        <attributes i:nil="true"/>
        <cast i:nil="true"/>
        <castUri>http://api.rovicorp.com/v1/movie/cast?format=xml&amp;apikey=141341&amp;movieid=V+++356492</castUri>
        <crew i:nil="true"/>
        <crewUri>http://api.rovicorp.com/v1/movie/crew?format=xml&amp;apikey=141341&amp;movieid=V+++356492</crewUri>
        <images i:nil="true"/>
        <imagesUri>http://api.rovicorp.com/v1/movie/images?format=xml&amp;apikey=141341&amp;movieid=V+++356492</imagesUri>
        <keywords i:nil="true"/>
        <keywordsUri>http://api.rovicorp.com/v1/movie/keywords?format=xml&amp;apikey=141341&amp;movieid=V+++356492</keywordsUri>
        <moods i:nil="true"/>
        <moodsUri>http://api.rovicorp.com/v1/movie/moods?format=xml&amp;apikey=141341&amp;movieid=V+++356492</moodsUri>
        <related i:nil="true"/>
        <relatedUri>http://api.rovicorp.com/v1/movie/related?format=xml&amp;apikey=141341&amp;movieid=V+++356492</relatedUri>
        <releases>
          <MovieRelease>
            <ids>
              <releaseId>E227644</releaseId>
              <upcId>097360718140</upcId>
            </ids>
            <title>Star Trek [Special Edition] [2 Discs] [Includes Digital Copy]</title>
            <studio>Paramount</studio>
            <rating>7</rating>
            <formats>
              <a:string>DVD</a:string>
            </formats>
            <year>2009 11 17</year>
            <hasCommentary>true</hasCommentary>
            <isPurchasable>true</isPurchasable>
          </MovieRelease>
          <MovieRelease>
            <ids>
              <releaseId>E227654</releaseId>
              <upcId>097363485049</upcId>
            </ids>
            <title>Star Trek</title>
            <studio>Paramount</studio>
            <rating>7</rating>
            <formats>
              <a:string>DVD</a:string>
            </formats>
            <year>2009 11 17</year>
            <hasCommentary>true</hasCommentary>
            <isPurchasable>true</isPurchasable>
          </MovieRelease>
          <MovieRelease>
            <ids>
              <releaseId>E228035</releaseId>
              <upcId>097360718249</upcId>
            </ids>
            <title>Star Trek [Special Edition] [3 Discs] [Includes Digital Copy] [Blu-ray]</title>
            <studio>Paramount</studio>
            <rating>7</rating>
            <formats>
              <a:string>Blu-ray</a:string>
            </formats>
            <year>2009 11 17</year>
            <hasCommentary>true</hasCommentary>
            <isPurchasable>true</isPurchasable>
          </MovieRelease>
          <MovieRelease>
            <ids>
              <releaseId>E232182</releaseId>
              <upcId>032429074553</upcId>
            </ids>
            <title>Star Trek [f.y.e. Exclusive Steelbook] [Special Edition] [Includes Digital Copy]</title>
            <studio>Paramount</studio>
            <rating>7</rating>
            <formats>
              <a:string>DVD</a:string>
            </formats>
            <year>2009 11 17</year>
            <hasCommentary>false</hasCommentary>
            <isPurchasable>false</isPurchasable>
          </MovieRelease>
          <MovieRelease>
            <ids>
              <releaseId>E253517</releaseId>
              <upcId>097363485063</upcId>
            </ids>
            <title>Star Trek [French]</title>
            <studio>Paramount Home Entertainment (Canadian)</studio>
            <rating>7</rating>
            <formats>
              <a:string>DVD</a:string>
            </formats>
            <year>2009 11 17</year>
            <hasCommentary>false</hasCommentary>
            <isPurchasable>false</isPurchasable>
          </MovieRelease>
          <MovieRelease>
            <ids>
              <releaseId>E248215</releaseId>
              <upcId>097361166247</upcId>
            </ids>
            <title>Star Trek [Blu-ray]</title>
            <studio>Paramount</studio>
            <rating>7</rating>
            <formats>
              <a:string>Blu-ray</a:string>
            </formats>
            <year>2010 10 19</year>
            <hasCommentary>false</hasCommentary>
            <isPurchasable>true</isPurchasable>
          </MovieRelease>
          <MovieRelease>
            <ids>
              <releaseId>E250976</releaseId>
              <upcId>097361166261</upcId>
            </ids>
            <title>Star Trek [Blu-ray]</title>
            <studio>Paramount Home Entertainment (Canadian)</studio>
            <rating>7</rating>
            <formats>
              <a:string>Blu-ray</a:string>
            </formats>
            <year>2010 11 09</year>
            <hasCommentary>false</hasCommentary>
            <isPurchasable>false</isPurchasable>
          </MovieRelease>
        </releases>
        <releasesUri>http://api.rovicorp.com/v1/movie/releases?format=xml&amp;apikey=141341&amp;movieid=V+++356492</releasesUri>
        <review i:nil="true"/>
        <reviewUri>http://api.rovicorp.com/v1/movie/review?format=xml&amp;apikey=141341&amp;movieid=V+++356492</reviewUri>
        <similar i:nil="true"/>
        <similarUri>http://api.rovicorp.com/v1/movie/similar?format=xml&amp;apikey=141341&amp;movieid=V+++356492</similarUri>
        <synopsis i:nil="true"/>
        <synopsisUri>http://api.rovicorp.com/v1/movie/synopsis?format=xml&amp;apikey=141341&amp;movieid=V+++356492</synopsisUri>
        <themes i:nil="true"/>
        <themesUri>http://api.rovicorp.com/v1/movie/themes?format=xml&amp;apikey=141341&amp;movieid=V+++356492</themesUri>
        <tones i:nil="true"/>
        <tonesUri>http://api.rovicorp.com/v1/movie/tones?format=xml&amp;apikey=141341&amp;movieid=V+++356492</tonesUri>
        <types i:nil="true"/>
        <typesUri>http://api.rovicorp.com/v1/movie/types?format=xml&amp;apikey=141341&amp;movieid=V+++356492</typesUri>
        <videos i:nil="true"/>
        <videosUri>http://api.rovicorp.com/v1/movie/videos?format=xml&amp;apikey=141341&amp;movieid=V+++356492</videosUri>
        <studio/>
        <producedBy>
          <a:string>Level 1 Entertainment</a:string>
          <a:string>Bad Robot Productions</a:string>
        </producedBy>
        <releasedBy>
          <a:string>Paramount Pictures</a:string>
        </releasedBy>
        <distributor i:nil="true"/>
      </movie>
    </result>
  </results>
</sortResponse>

Error Codes

CodeDescription
400 Incorrect or invalid request. The reason is shown in the Message object in ControlSet.

See Also

↑ Top

Personal tools