Search

Tools

Bookmark This Page

Match/Filename

Returns Rovi IDs for a song, movie, or TV series on your CDs, DVDs, Blu-rays, and other entertainment media, 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.

Syntax

catalog/match/filename?apikey=apikey&sig=sig&name=name [&entitytype=entitytype] [&include=include] [&format=format] [&size=size]

Request Example 1

Get IDs for the song Billie Jean and include a review for verification.

http://api.rovicorp.com/recognition/v2.1/music/match/filename?apikey=apikey&sig=sig&
name=billie+jean+06.cda&include=review

Request Example 2

Get IDs for the TV series Breaking Bad in an XML response and include links to the seasons.

http://api.rovicorp.com/recognition/v2.1/video/match/filename?apikey=apikey&sig=sig&
name=breaking-bad-S04E03.vob&entitytype=tvseries&include=seasons&format=xml

Request Parameters

♫ Music-related requests ⊑⊒ TV-related requests

Parameter Required Description

apikey Yes Access code that authorizes your request for data from Rovi.

catalog

Yes

Database to match against.

To match against . . .	Specify this catalog.
music tracks	music ♫
movies and videos	video ⊑⊒

name Yes URL-encoded name of the file.

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.

entitytype

For a catalog type of video, categories that further narrow the type of content to match against.

To match against . . .	Specify this entitytype.
TV series	tvseries
movies	movie

If not specified for a catalog type of video, both categories are searched. Order of results is determined by relevance, however, so the top results may come from just one of the entity types.

format

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.

include

Additional data to include in each result returned. To include cast members in movie results, for example, specify include=movie:cast. For multiple includes, separate the values with commas like this: include=movie:moods,crew. For multiple entity types, specify separate parameters like this: include=movie:cast,crew&include=tvseries:cast,crew. A request can contain up to 20 include values.

For catalog:	You can include these results . . .
music ♫	All	All of the data available.
	Appearances	Albums and videos the song appears on.
	Review	The most recent review of the song.
	Sample	URL to an audio sample. Note: Access to audio samples is governed by your subscription level.
video ⊑⊒	Awards	Awards a movie or program has been nominated for or won.
	Cast	Cast information and images.
	Crew	Crew information and images.
	Images	Links to images for a movie or program.
	Keywords	Keywords that describe characteristics of a movie or program.
	Moods	Terms that describe expressive characteristics of a movie or program.
	Parentalratings	Parental ratings for a movie or program.
	Related	Titles of related movies and programs.
	Review	Review of a movie or program.
	Seasons	Links to information about seasons and episodes in a television series.
	Synopsis	Synopsis of a movie or program.
	Themes	Topics and circumstances that motivate or fit with a movie or program.
	Tones	Feelings and attitudes that motivate or fit with a movie or program.

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

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

size No The number of items you want to be returned. The default is 20.

Response

Response Header

Response	Type	Description
controlSet	ControlSet	The HTTP response status.
id	String	Server transaction ID for the response.

Response for Match/Filename

Response	Type	Description
results	result [ ]	Information about items that match the criteria specified in the request, listed in order of relevance.

Response Example 1

Here's the response to Request Example 1, looking for IDs for the song file Billie Jean. Just the top result is requested here to show as a sample.

Requested with http://api.rovicorp.com/recognition/v2.1/music/match/filename?apikey=apikey&sig=sig&
name=billie+jean+06.cda&include=review&size=1

{
   "matchResponse":{
      "meta:id":"tul1cpgssrapp1:gwy:2w3j3",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"song",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.1
               }
            ],
            "id":"MT0000149626",
            "messages":null,
            "song":{
               "ids":{
                  "amgClassicalTrackId":null,
                  "amgPopTrackId":null,
                  "isrcId":"USSM19902991",
                  "muzeId":"2771990",
                  "trackId":"MT0000149626"
               },
               "title":"Billie Jean",
               "primaryArtists":[
                  {
                     "id":"MN0000467203",
                     "name":"Michael Jackson"
                  }
               ],
               "isPick":true,
               "genres":[
                  {
                     "id":"MA0000002809",
                     "name":"R&B",
                     "weight":10
                  }
               ],
               "appearances":null,
               "appearancesUri":"http://api.rovicorp.com/v1/song/appearances?format=json&apikey=141341&trackId=MT0000149626",
               "moods":null,
               "moodsUri":null,
               "review":{
                  "text":"[roviLink=\"MN\"]Quincy Jones[/roviLink] had objections to [roviLink=\"MN\"]Michael Jackson[/roviLink]'s [roviLink=\"MC\"]\"Billie Jean.\"[/roviLink] The veteran composer/arranger/producer thought that the title would be confusing, leading listeners to think that the title referred to pro tennis player [roviLink=\"MN\"]Billie Jean King[/roviLink]. It was suggested that the title be changed to [roviLink=\"MC\"]\"Not My Lover.\"[/roviLink] Actually, the song's title character was based on all the women who'd brought maternity suits against [roviLink=\"MN\"]Jackson[/roviLink] and his brothers when they were known as [roviLink=\"MN\"]the Jackson 5[/roviLink]. The session list for [roviLink=\"MC\"]\"Billie Jean\"[/roviLink] listed drummer [roviLink=\"MN\"]Leon \"Ndugu\" Chancler[/roviLink],[roviLink=\"MN\"]Brothers Johnson[/roviLink] bassist [roviLink=\"MN\"]Louis Johnson[/roviLink],[roviLink=\"MN\"]Michael Boddicker[/roviLink] on the Emu Emulator sampling keyboard, and synth players [roviLink=\"MN\"]Greg Phillinganes[/roviLink], [roviLink=\"MN\"]Bill Wolfer[/roviLink], and [roviLink=\"MN\"]Greg Smith[/roviLink]. [roviLink=\"MN\"]Tom Scott[/roviLink] blows an interwoven lyricon line throughout the track. As the follow-up to [roviLink=\"MC\"]\"The Girl Is Mine,\"[/roviLink] the first single from [roviLink=\"MW\"]Thriller[/roviLink],[roviLink=\"MC\"]\"Billie Jean\"[/roviLink] sold more than two million copies, staying at number one [roviLink=\"MA\"]R&B[/roviLink] for nine weeks and number one [roviLink=\"MA\"]pop[/roviLink] for seven weeks in early 1983. Who can forget [roviLink=\"MN\"]Jackson[/roviLink]'s sensational performance of the song during the May 1983 [roviLink=\"MN\"]NBC[/roviLink] broadcast of the [roviLink=\"VW\"]Motown 25[/roviLink] special which boasted the first public showing of his gravity-defying moonwalk dance? Or the song's stylish, trend-setting music video. Ironically around the time of [roviLink=\"MC\"]\"Billie Jean\"[/roviLink]'s release,[roviLink=\"MN\"]Jackson[/roviLink] was slapped with a paternity suit. ~ Ed Hogan",
                  "author":"Ed Hogan"
               },
               "reviewUri":"http://api.rovicorp.com/v1/song/review?format=json&apikey=141341&trackId=MT0000149626",
               "styles":null,
               "stylesUri":"http://api.rovicorp.com/v1/song/styles?format=json&apikey=141341&trackId=MT0000149626",
               "themes":null,
               "themesUri":null,
               "sample":null,
               "sampleUri":"http://api.rovicorp.com/v1/song/sample?format=json&apikey=141341&trackId=MT0000149626"
            }
         }
      ]
   }
}

Response Example 2

Here's the response to Request Example 2, looking for IDs for the TV series Breaking Bad in an XML response along with links to seasons. Just the top result is requested here to show as a sample.

Requested with http://api.rovicorp.com/recognition/v2.1/video/match/filename?apikey=apikey&sig=sig&
entitytype=tvseries&name=breaking-bad-S04E03.vob&include=seasons&format=xml&size=1

<matchResponse 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="tul1cpgssrapp2:gwy:2vx3o">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true"/>
  </controlSet>
  <results>
    <result>
      <type>tvseries</type>
      <relevance>
        <code>Score</code>
        <value>0.45</value>
      </relevance>
      <availabilties/>
      <id>7221538</id>
      <messages i:nil="true"/>
      <video>
        <ids>
          <amgMovieId i:nil="true"/>
          <cosmoId>7221538</cosmoId>
          <iguideId>7221538</iguideId>
        </ids>
        <seriesIds i:nil="true"/>
        <masterTitle>Breaking Bad</masterTitle>
        <secondaryTitle/>
        <episodeTitle i:nil="true"/>
        <category>Other</category>
        <color>Color</color>
        <lastAirDate i:nil="true"/>
        <originalAirDate>2008-01-20T00:00:00Z</originalAirDate>
        <programType>Series</programType>
        <releaseYear>2008</releaseYear>
        <duration>60</duration>
        <subcategory>comedy-drama</subcategory>
        <syndicated>false</syndicated>
        <programLanguage>English</programLanguage>
        <partNumber i:nil="true"/>
        <partTotal i:nil="true"/>
        <parentalRatings i:nil="true"/>
        <parentalRatingsUri>http://api.rovicorp.com/v1/video/parentalratings?format=xml&amp;apikey=141341&amp;cosmoid=7221538</parentalRatingsUri>
        <cast i:nil="true"/>
        <castUri>http://api.rovicorp.com/v1/video/cast?format=xml&amp;apikey=141341&amp;cosmoid=7221538</castUri>
        <crew i:nil="true"/>
        <crewUri>http://api.rovicorp.com/v1/video/crew?format=xml&amp;apikey=141341&amp;cosmoid=7221538</crewUri>
        <awards i:nil="true"/>
        <awardsUri>http://api.rovicorp.com/v1/video/awards?format=xml&amp;apikey=141341&amp;cosmoid=7221538</awardsUri>
        <images i:nil="true"/>
        <imagesUri>http://api.rovicorp.com/v1/video/images?format=xml&amp;apikey=141341&amp;cosmoid=7221538</imagesUri>
        <clip i:nil="true"/>
        <clipUri i:nil="true"/>
        <seasons>
          <VideoSeason>
            <number>0</number>
            <episodesUri>http://api.rovicorp.com/v1/video/season/0/info?format=xml&amp;apikey=141341&amp;cosmoid=7221538</episodesUri>
          </VideoSeason>
          <VideoSeason>
            <number>4</number>
            <seasonInfoUri>http://api.rovicorp.com/v1/video/season/4/info?format=xml&amp;apikey=141341&amp;cosmoid=7221538</seasonInfoUri>
            <episodesUri>http://api.rovicorp.com/v1/video/season/4/episodes?format=xml&amp;apikey=141341&amp;cosmoid=7221538</episodesUri>
          </VideoSeason>
          <VideoSeason>
            <number>3</number>
            <seasonInfoUri>http://api.rovicorp.com/v1/video/season/3/info?format=xml&amp;apikey=141341&amp;cosmoid=7221538</seasonInfoUri>
            <episodesUri>http://api.rovicorp.com/v1/video/season/3/episodes?format=xml&amp;apikey=141341&amp;cosmoid=7221538</episodesUri>
          </VideoSeason>
          <VideoSeason>
            <number>2</number>
            <seasonInfoUri>http://api.rovicorp.com/v1/video/season/2/info?format=xml&amp;apikey=141341&amp;cosmoid=7221538</seasonInfoUri>
            <episodesUri>http://api.rovicorp.com/v1/video/season/2/episodes?format=xml&amp;apikey=141341&amp;cosmoid=7221538</episodesUri>
          </VideoSeason>
          <VideoSeason>
            <number>1</number>
            <seasonInfoUri>http://api.rovicorp.com/v1/video/season/1/info?format=xml&amp;apikey=141341&amp;cosmoid=7221538</seasonInfoUri>
            <episodesUri>http://api.rovicorp.com/v1/video/season/1/episodes?format=xml&amp;apikey=141341&amp;cosmoid=7221538</episodesUri>
          </VideoSeason>
        </seasons>
        <seasonsUri>http://api.rovicorp.com/v1/video/seasons?format=xml&amp;apikey=141341&amp;cosmoid=7221538</seasonsUri>
        <variants i:nil="true"/>
        <variantsUri>http://api.rovicorp.com/v1/video/variants?format=xml&amp;apikey=141341&amp;cosmoid=7221538</variantsUri>
        <schedule i:nil="true"/>
        <scheduleUri i:nil="true"/>
        <event i:nil="true"/>
        <eventUri i:nil="true"/>
        <keywords i:nil="true"/>
        <keywordsUri i:nil="true"/>
        <moods i:nil="true"/>
        <moodsUri i:nil="true"/>
        <related i:nil="true"/>
        <relatedUri>http://api.rovicorp.com/v1/video/related?format=xml&amp;apikey=141341&amp;cosmoid=7221538</relatedUri>
        <review i:nil="true"/>
        <reviewUri i:nil="true"/>
        <synopsis i:nil="true"/>
        <synopsisUri>http://api.rovicorp.com/v1/video/synopsis?format=xml&amp;apikey=141341&amp;cosmoid=7221538</synopsisUri>
        <themes i:nil="true"/>
        <themesUri>http://api.rovicorp.com/v1/video/themes?format=xml&amp;apikey=141341&amp;cosmoid=7221538</themesUri>
        <tones i:nil="true"/>
        <tonesUri i:nil="true"/>
      </video>
    </result>
  </results>
</matchResponse>

Error Codes

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

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

Topics