Search

Tools

Bookmark This Page

Match/Track

Returns Rovi IDs for a song in your catalog in order of confidence level, based on title and field-level data, along with data you can use to verify a match with the song.

Note: The primary Rovi ID for a song is the track ID.

Syntax

music/match/track?apikey=apikey&sig=sig&name=name [&albumtitle=albumtitle] [&isrc=isrc] [&medianumber=medianumber] [&performername=performername] [&seconds=seconds] [&sequencenumber=sequencenumber] [&include=include] [&size=size] [&format=format]

Request Example 1

Get IDs for the rap song Deeper, by THEESatisfaction, and verify by returning releases it appears on.

http://api.rovicorp.com/recognition/v2.1/music/match/track?apikey=apikey&sig=sig&name=Deeper&
performername=THEESatisfaction&include=appearances

Request Example 2

Get IDs for Robert Johnson's Cross Road Blues in an XML response along with a review.

http://api.rovicorp.com/recognition/v2.1/music/match/track?apikey=apikey&sig=sig&
name=Cross+Road+Blues&performername=Robert+Johnson&include=review&format=xml

Request Example 3

Get IDs for the song Flamenco Sketches, the first song on an album, and include a link to a sample. Note: Access to song samples is governed by your subscription level.

http://api.rovicorp.com/recognition/v2.1/music/match/track?apikey=apikey&sig=sig&
name=Flamenco+Sketches&sequencenumber=1&include=sample

Request Parameters

Parameter Required Description

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

name Yes Keywords from the song title. This searches for the most popular title with that combination of words. Replace spaces with plus (+) or percent20 (%20) symbols.

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.

albumtitle No Keywords from the album title. This searches for the most popular title with that combination of words. Replace spaces with plus (+) or percent20 (%20) symbols.

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 album appearances in the response, for example, add include=appearances. For multiple includes, separate the values with commas like this: include=appearances,review. You can also include all data with include=all. The possible values are:

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.

This additional data comes from Rovi Music. For information about the data returned by an include value, click on the include value.

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.

isrc No International Standard Recording Code (ISRC) for a song recording. Note: Because some recordings have the same ISRC code as another recording or have multiple ISRC codes, you need to verify results of requests that use ISRC codes that come from outside of Rovi Cloud Services. The song you want may be available under a different ISRC code.

medianumber No Number of the disc in the series that the track is on.

performername No Name of a performer on the song. To specify multiple performers, add additional parameters like this: performername=Michael+Jackson&performername=Paul+McCartney.

seconds No Playing time in seconds.

sequencenumber No Number of the track on the album.

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/Track

Response	Type	Description
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 rap song Deeper, by THEESatisfaction. Just the top result is requested here to show as a sample.

Requested with http://api.rovicorp.com/recognition/v2.1/music/match/track?apikey=apikey&sig=sig&
name=Deeper&performername=THEESatisfaction&include=appearances&size=1.

{
   "matchResponse":{
      "meta:id":"tul1cpgssrapp1:gwy:2vvo7",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"song",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.44896722
               }
            ],
            "id":"MT0043137880",
            "messages":null,
            "song":{
               "ids":{
                  "amgClassicalTrackId":null,
                  "amgPopTrackId":"T 25566231",
                  "isrcId":null,
                  "muzeId":"35066948",
                  "trackId":"MT0043137880"
               },
               "title":"Deeper",
               "primaryArtists":[
                  {
                     "id":"MN0002863147",
                     "name":"THEESatisfaction"
                  }
               ],
               "isPick":true,
               "genres":[
                  {
                     "id":"MA0000002816",
                     "name":"Rap",
                     "weight":9
                  },
                  {
                     "id":"MA0000002613",
                     "name":"Pop/Rock",
                     "weight":5
                  }
               ],
               "appearances":[
                  {
                     "ids":{
                        "albumId":"MW0002303081",
                        "releaseId":"MR0003566758",
                        "trackId":"MT0043137880"
                     },
                     "title":"awE naturalE",
                     "label":"Sub Pop",
                     "year":"2012-03-27",
                     "rating":8,
                     "isPick":true,
                     "hasReview":true,
                     "sample":"",
                     "duration":0
                  },
                  {
                     "ids":{
                        "albumId":"MW0002303081",
                        "releaseId":"MR0003576931",
                        "trackId":"MT0043162832"
                     },
                     "title":"awE naturalE",
                     "label":"Sub Pop",
                     "year":"2012-03-27",
                     "rating":8,
                     "isPick":true,
                     "hasReview":true,
                     "sample":"",
                     "duration":0
                  },
                  {
                     "ids":{
                        "albumId":"MW0002303081",
                        "releaseId":"MR0003589135",
                        "trackId":"MT0043820527"
                     },
                     "title":"awE naturalE",
                     "label":"Sub Pop",
                     "year":"2012-03-27",
                     "rating":8,
                     "isPick":true,
                     "hasReview":true,
                     "sample":"http://actual-url-concealed.mp3",
                     "duration":226
                  }
               ],
               "appearancesUri":"http://api.rovicorp.com/v1/song/appearances?format=json&apikey=141341&trackId=MT0043137880",
               "moods":null,
               "moodsUri":null,
               "review":null,
               "reviewUri":null,
               "styles":null,
               "stylesUri":"http://api.rovicorp.com/v1/song/styles?format=json&apikey=141341&trackId=MT0043137880",
               "themes":null,
               "themesUri":null,
               "sample":null,
               "sampleUri":"http://api.rovicorp.com/v1/song/sample?format=json&apikey=141341&trackId=MT0043137880"
            }
         }
      ]
   }
}

Response Example 2

Here's the response to Request Example 2, looking for Robert Johnson's Cross Road Blues 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/music/match/track?apikey=apikey&sig=sig&
name=Cross+Road+Blues&performername=Robert+Johnson&include=review&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:2vpcr">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true"/>
  </controlSet>
  <results>
    <result>
      <type>song</type>
      <relevance>
        <code>Score</code>
        <value>0.45000002</value>
      </relevance>
      <availabilties/>
      <id>MT0000372673</id>
      <messages i:nil="true"/>
      <song>
        <ids>
          <amgClassicalTrackId i:nil="true"/>
          <amgPopTrackId>T 4056641</amgPopTrackId>
          <isrcId i:nil="true"/>
          <muzeId>4919595</muzeId>
          <trackId>MT0000372673</trackId>
        </ids>
        <title>Cross Road Blues</title>
        <primaryArtists>
          <AlbumArtist>
            <id>MN0000832288</id>
            <name>Robert Johnson</name>
          </AlbumArtist>
        </primaryArtists>
        <isPick>true</isPick>
        <genres>
          <Genre>
            <id>MA0000002467</id>
            <name>Blues</name>
            <weight>8</weight>
          </Genre>
        </genres>
        <appearances i:nil="true"/>
        <appearancesUri>http://api.rovicorp.com/v1/song/appearances?format=xml&amp;apikey=141341&amp;trackId=MT0000372673</appearancesUri>
        <moods i:nil="true"/>
        <moodsUri>http://api.rovicorp.com/v1/song/moods?format=xml&amp;apikey=141341&amp;trackId=MT0000372673</moodsUri>
        <review>
          <text>One of [roviLink=&quot;MN&quot;]Robert Johnson’s[/roviLink] masterpieces, and one of his most popular songs with other performers, “Cross Road Blues” is a staggering display of poetry with quite masterly guitar playing; indeed, it is the song that contributed to much of the myth of [roviLink=&quot;MN&quot;]Robert Johnson[/roviLink]. The song’s lyrics are amazing – it opens with the definitive “I went down to the crossroad, fell down on my knees/I went down to the crossroad, fell down on my knees/Asked the Lord above “Have mercy now save poor Bob if you please””, sung in a haunting, otherworldly voice that almost defies adequate description. The guitar playing too, is complex, yet delicate and immensely tuneful – indeed, it’s been compared to [roviLink=&quot;MN&quot;]Bach[/roviLink], and you can understand the comparison. “Cross Road Blues” is one of [roviLink=&quot;MN&quot;]Johnson’s[/roviLink] finest songs, it’s lyric is myth-making, and the subject matter has influenced hundreds of blues songs since. ~ Thomas Ward</text>
          <author>Thomas Ward</author>
        </review>
        <reviewUri>http://api.rovicorp.com/v1/song/review?format=xml&amp;apikey=141341&amp;trackId=MT0000372673</reviewUri>
        <styles i:nil="true"/>
        <stylesUri>http://api.rovicorp.com/v1/song/styles?format=xml&amp;apikey=141341&amp;trackId=MT0000372673</stylesUri>
        <themes i:nil="true"/>
        <themesUri>http://api.rovicorp.com/v1/song/themes?format=xml&amp;apikey=141341&amp;trackId=MT0000372673</themesUri>
        <sample i:nil="true"/>
        <sampleUri>http://api.rovicorp.com/v1/song/sample?format=xml&amp;apikey=141341&amp;trackId=MT0000372673</sampleUri>
      </song>
    </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/track

Topics