Search

Tools

Bookmark This Page

Match/Album

Returns Rovi IDs for an album 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 album.

Note: The primary Rovi ID for an album is the album ID.

Syntax

music/match/album?apikey=apikey&sig=sig&name=name [&ean=ean] [&labelname=labelname] [&numtracks=numtracks] [&performername=performername] [&releasedate=releasedate] [&upc=upc] [&include=include] [&size=size] [&format=format]

Request Example 1

Get IDs for the Carolin Widmann, Alexander Lonquich performances of Schubert's Fantasie, Rondo, and Violin Sonata, and include images and releases for verification.

http://api.rovicorp.com/recognition/v2.1/music/match/album?apikey=apikey&sig=sig&
name=Schubert+Fantasie&performername=Widmann&performername=Lonquich&
include=images,releases

Request Example 2

Get IDs of the album Between the Times and the Tides in an XML response and include a list of releases.

http://api.rovicorp.com/recognition/v2.1/music/match/album?apikey=apikey&sig=sig&
name=between+the+tides&labelname=matador&format=xml&include=releases

Request Parameters

Parameter Required Description

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

name Yes 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.

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.

ean No The numbers from the EAN barcode that identifies the release.

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

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

Notice: The value Similar is deprecated and will be removed from the API on a date to be announced.

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.

labelname No Record company that released the album.

numtracks No Number of tracks on the album.

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

releasedate No Date the album was released in YYYYMMDD format.

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

upc

The numbers from the barcode that identifies a music release:

14 digits for music downloads
Fewer than 14 digits for CDs, DVDs, and other physical products

Response

Response Header

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

Response for Match/Album

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 IDs for the Carolin Widmann, Alexander Lonquich performances of Schubert's seldom performed works, Fantasie, Rondo, and Violin Sonata, along with releases and album images. Just the top result is requested here to show as a sample.

Requested with http://api.rovicorp.com/recognition/v2.1/music/match/album?apikey=apikey&sig=sig&
name=Schubert+Fantasie&performername=Widmann&performername=Lonquich&
include=classicalreview&size=1

{
   "matchResponse":{
      "meta:id":"tul1cpgssrapp2:gwy:4qvcd",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"album",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.4764706
               }
            ],
            "id":"MW0002289331",
            "messages":null,
            "album":{
               "ids":{
                  "albumId":"MW0002289331",
                  "amgClassicalId":"W 277308",
                  "amgPopId":null
               },
               "title":"Schubert: Fantasie; Rondo; Sonate",
               "primaryArtists":[
                  {
                     "id":"MN0002202960",
                     "name":"Alexander Lonquich"
                  },
                  {
                     "id":"MN0002297283",
                     "name":"Carolin Widmann"
                  }
               ],
               "guestArtists":null,
               "flags":[
                  "Instrumental"
               ],
               "duration":3737,
               "originalReleaseDate":"2012-02-06",
               "rating":7,
               "isPick":false,
               "genres":[
                  {
                     "id":"MA0000002521",
                     "name":"Classical",
                     "weight":5
                  }
               ],
               "headlineReview":{
                  "text":"[roviLink=\"MN0002297283\"]Widmann[/roviLink] and [roviLink=\"MN0002202960\"]Lonquich[/roviLink] bring their skills for modern music to bear on these seldom-heard pieces for violin and piano.",
                  "author":"James Manheim"
               },
               "classicalReview":null,
               "classicalReviewUri":"http://stg-api.rovicorp.com/v1/album/classicalReview?format=json&apikey=141341&albumid=MW0002289331",
               "credits":null,
               "creditsUri":"http://api.rovicorp.com/v1/album/credits?format=json&apikey=141341&albumid=MW0002289331",
               "images":[
                  {
                     "front":[
                        {
                           "height":66,
                           "width":75,
                           "formatid":71,
                           "url":"http://actual-url-concealed.jpg",
                           "author":"",
                           "copyrightOwner":""
                        },
                        {
                           "height":150,
                           "width":170,
                           "formatid":63,
                           "url":"http://actual-url-concealed.jpg",
                           "author":"",
                           "copyrightOwner":""
                        },
                        {
                           "height":221,
                           "width":250,
                           "formatid":44,
                           "url":"http://actual-url-concealed.jpg",
                           "author":"",
                           "copyrightOwner":""
                        },
                        {
                           "height":355,
                           "width":400,
                           "formatid":64,
                           "url":"http://actual-url-concealed.jpg",
                           "author":"",
                           "copyrightOwner":""
                        },
                        {
                           "height":443,
                           "width":500,
                           "formatid":16,
                           "url":"http://actual-url-concealed.jpg",
                           "author":"",
                           "copyrightOwner":""
                        },
                        {
                           "height":958,
                           "width":1080,
                           "formatid":62,
                           "url":"http://actual-url-concealed.jpg",
                           "author":"",
                           "copyrightOwner":""
                        }
                     ]
                  }
               ],
               "imagesUri":"http://api.rovicorp.com/v1/album/images?format=json&apikey=141341&albumid=MW0002289331",
               "moods":null,
               "moodsUri":null,
               "primaryReview":null,
               "primaryReviewUri":null,
               "releases":[
                  {
                     "ids":{
                        "albumId":"MW0002289331",
                        "amgClassicalId":"W 277308",
                        "amgPopId":null,
                        "eanId":null,
                        "releaseId":"MR0003549037",
                        "upcId":"028947645467"
                     },
                     "title":"Schubert: Fantasie; Rondo; Sonate",
                     "label":"ECM",
                     "format":"CD",
                     "releaseDate":"2012-02-06",
                     "isMain":true,
                     "isPurchasable":true
                  },
                  {
                     "ids":{
                        "albumId":"MW0002289331",
                        "amgClassicalId":"W 277393",
                        "amgPopId":null,
                        "eanId":null,
                        "releaseId":"MR0003549658",
                        "upcId":null
                     },
                     "title":"Schubert: Fantasie; Rondo; Sonate",
                     "label":"ECM / ECM New Series / Universal Music Group",
                     "format":"Digital Download",
                     "releaseDate":"2012-02-21",
                     "isMain":false,
                     "isPurchasable":false
                  }
               ],
               "releasesUri":"http://api.rovicorp.com/v1/album/releases?format=json&apikey=141341&albumid=MW0002289331",
               "similar":null,
               "similarUri":null,
               "styles":null,
               "stylesUri":"http://api.rovicorp.com/v1/album/styles?format=json&apikey=141341&albumid=MW0002289331",
               "themes":null,
               "themesUri":null,
               "tracks":null,
               "tracksUri":"http://api.rovicorp.com/v1/album/tracks?format=json&apikey=141341&albumid=MW0002289331"
            }
         }
      ]
   }
}

Response Example 2

Here's the response to Request Example 2, looking for IDs of the album Between the Times and the Tides along with a list of releases. Just the top result is requested here to show as a sample.

Requested with http://api.rovicorp.com/recognition/v2.1/music/match/album?apikey=apikey&sig=sig&
name=between+the+tides&label=matador&format=xml&include=releases&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:2vi58">
  <controlSet>
    <status>ok</status>
    <code>200</code>
    <messages i:nil="true"/>
  </controlSet>
  <results>
    <result>
      <type>album</type>
      <relevance>
        <code>Score</code>
        <value>0.2987508</value>
      </relevance>
      <availabilties/>
      <id>MW0002293926</id>
      <messages i:nil="true"/>
      <album>
        <ids>
          <albumId>MW0002293926</albumId>
          <amgClassicalId i:nil="true"/>
          <amgPopId>R 2385103</amgPopId>
        </ids>
        <title>Between the Times and the Tides</title>
        <primaryArtists>
          <AlbumArtist>
            <id>MN0000813019</id>
            <name>Lee Ranaldo</name>
          </AlbumArtist>
        </primaryArtists>
        <guestArtists i:nil="true"/>
        <flags i:nil="true"/>
        <duration>2853</duration>
        <originalReleaseDate>2012-03-20</originalReleaseDate>
        <rating>7</rating>
        <isPick>false</isPick>
        <genres>
          <Genre>
            <id>MA0000002613</id>
            <name>Pop/Rock</name>
            <weight>5</weight>
          </Genre>
        </genres>
        <headlineReview>
          <text>This dreamy, poetic solo album proves that Lee Ranaldo can remain true to himself and reveal new things at the same time.</text>
          <author>Heather Phares</author>
        </headlineReview>
        <classicalReview i:nil="true"/>
        <classicalReviewUri i:nil="true"/>
        <credits i:nil="true"/>
        <creditsUri>http://api.rovicorp.com/v1/album/credits?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</creditsUri>
        <images i:nil="true"/>
        <imagesUri>http://api.rovicorp.com/v1/album/images?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</imagesUri>
        <moods i:nil="true"/>
        <moodsUri>http://api.rovicorp.com/v1/album/moods?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</moodsUri>
        <primaryReview i:nil="true"/>
        <primaryReviewUri>http://api.rovicorp.com/v1/album/primaryReview?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</primaryReviewUri>
        <releases>
          <AlbumRelease>
            <ids>
              <albumId>MW0002293926</albumId>
              <amgClassicalId i:nil="true"/>
              <amgPopId>R 2385103</amgPopId>
              <eanId i:nil="true"/>
              <releaseId>MR0003554889</releaseId>
              <upcId>744861098027</upcId>
            </ids>
            <title>Between The Times And Tides</title>
            <label>Matador / Matador Records</label>
            <format>CD</format>
            <releaseDate>2012-03-19</releaseDate>
            <isMain>true</isMain>
            <isPurchasable>true</isPurchasable>
          </AlbumRelease>
          <AlbumRelease>
            <ids>
              <albumId>MW0002293926</albumId>
              <amgClassicalId i:nil="true"/>
              <amgPopId>R 2397225</amgPopId>
              <eanId i:nil="true"/>
              <releaseId>MR0003567204</releaseId>
              <upcId>0744861098010</upcId>
            </ids>
            <title>Between the Times and the Tides</title>
            <label>Matador</label>
            <format>LP</format>
            <releaseDate>2012-03-19</releaseDate>
            <isMain>false</isMain>
            <isPurchasable>true</isPurchasable>
          </AlbumRelease>
        </releases>
        <releasesUri>http://api.rovicorp.com/v1/album/releases?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</releasesUri>
        <similar i:nil="true"/>
        <similarUri i:nil="true"/>
        <styles i:nil="true"/>
        <stylesUri>http://api.rovicorp.com/v1/album/styles?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</stylesUri>
        <themes i:nil="true"/>
        <themesUri>http://api.rovicorp.com/v1/album/themes?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</themesUri>
        <tracks i:nil="true"/>
        <tracksUri>http://api.rovicorp.com/v1/album/tracks?format=xml&amp;apikey=141341&amp;albumid=MW0002293926</tracksUri>
      </album>
    </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/album

Topics