Media-recognition-api/v2.1/match/video

Jump to: navigation, search

Match/Video

Matches title and field-level criteria against movies, TV series, and TV programs in Rovi Cloud Services and returns results in order of match.

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

Find the Star Trek series that started in 1995 and request awards in the response.
http://api.rovicorp.com/recognition/v2.1/video/match/video?apikey=apikey&sig=sig&title=star+trek&
entitytype=tvseries&releaseyear=1995&include=awards

Request Example 2

Look for the movies titled House of Numbers and return a synopsis of each one.
http://api.rovicorp.com/recognition/v2.1/video/match/video?apikey=apikey&sig=sig&
title=house+of+numbers&entitytype=movie&include=synopsis

Request Example 3

Find the latest Star Trek movie by a UPC code and request a list of DVD releases in an XML response.
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

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
id String

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 the Star Trek series that started in 1995 and requesting awards 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":null,
               "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":[
                  {
                     "recipients":[
                        {
                           "ids":{
                              "amgClassicalId":null,
                              "amgMovieId":null,
                              "amgPopId":null,
                              "cosmoId":"161806",
                              "nameId":null
                           },
                           "fullName":"Jerry Goldsmith",
                           "nameUri":"http://api.rovicorp.com/v1/name/info?format=json&apikey=141341&cosmoid=161806",
                           "isCelebrity":true,
                           "isOrganization":false
                        }
                     ],
                     "ids":{
                        "amgMovieId":null,
                        "cosmoId":"857974",
                        "iguideId":null
                     },
                     "title":"Star Trek: Voyager",
                     "type":"Emmy",
                     "medium":"None",
                     "category":"Outstanding Individual Achievement in Main Title Theme Music",
                     "year":1995,
                     "isWinner":true
                  }
               ],
               "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",
               "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 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

Retrieved from "http://prod-doc.rovicorp.com/mashery/index.php/Media-recognition-api/v2.1/match/video"
Personal tools