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

Jump to: navigation, search

Match/Album

Matches title and field-level criteria against albums in Rovi Cloud Services and returns results in order of match.

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 the review of the Carolin Widmann, Alexander Lonquich performances of Schubert's Fantasie, Rondo, and Violin Sonata.
http://api.rovicorp.com/recognition/v2.1/music/match/album?apikey=apikey&sig=sig&
name=Schubert+Fantasie&performername=Widmann&performername=Lonquich& include=classicalreview

Request Example 2

Get the releases of the album Between the Times and the Tides in an XML response.
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

ParameterRequiredDescription
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 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.

include No 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 to immediately display.
  • 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 No 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

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

Response for Match/Album

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 review of the Carolin Widmann, Alexander Lonquich performances of Schubert's seldom performed works, Fantasie, Rondo, and Violin Sonata. 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:2vihb",
      "controlSet":{
         "status":"ok",
         "code":200,
         "messages":null
      },
      "results":[
         {
            "type":"album",
            "relevance":[
               {
                  "code":"Score",
                  "value":0.41250002
               }
            ],
            "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":"Patsy Morita"
               },
               "classicalReview":{
                  "text":"German violinist [roviLink=\"MN0002297283\"]Carolin Widmann[/roviLink] has specialized mostly in contemporary repertory, and her approach to [roviLink=\"MN0000691239\"]Schubert[/roviLink] bears the marks of that specialty: her playing here is spiky, given to emphasis on small structural details, full of sharp contrasts without being especially high in sentiment. You might or might not like it as a general rule, but here it fulfills her purpose and that of pianist [roviLink=\"MN0002202960\"]Alexander Lonquich[/roviLink]. [roviLink=\"MN0000691239\"]Schubert[/roviLink]'s comparatively sparse output for violin and piano has never gotten its due, and [roviLink=\"MN0002297283\"]Widmann[/roviLink]'s reading here compels the listener to take the music seriously. [roviLink=\"MN0000691239\"]Schubert[/roviLink]'s late [roviLink=\"MA\"]piano sonatas[/roviLink], last [roviLink=\"MA\"]symphony[/roviLink], and late choral music are so heavily programmed that it may come as a surprise to learn of other works of the period that are equal to these in quality, yet are not often heard. That's exactly what you get with the [roviLink=\"MC0002359251\"]Fantasie for violin and piano in C major, D. 934[/roviLink], and the [roviLink=\"MC0002372002\"]Rondo for violin and piano in B minor, D. 895[/roviLink]. The [roviLink=\"MC0002359251\"]Fantasie[/roviLink] is a close cousin to the [roviLink=\"MC0002394265\"]Wanderer Fantasie for piano[/roviLink], but is not structured exactly like it; it has semi-independent movements, with a [roviLink=\"MA\"]reprise[/roviLink] of its haunting opening material following one of [roviLink=\"MN0000691239\"]Schubert[/roviLink]'s great long slow movements. The [roviLink=\"MA\"]rondo[/roviLink], despite its neutral title, is a work of great emotional profundity. The [roviLink=\"MC0002375183\"]Violin Sonata in A major, D. 574[/roviLink], a fine essay in Beethovenian style (which not too many composers, let alone one 20 years old, could execute convincingly in 1817), rounds out the program satisfyingly. With the usual superb production from [roviLink=\"MN\"]ECM[/roviLink] label head [roviLink=\"MN0000674652\"]Manfred Eicher[/roviLink], this is a must for any serious [roviLink=\"MN0000691239\"]Schubert[/roviLink] collection.",
                  "author":"James Manheim"
               },
               "classicalReviewUri":"http://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":null,
               "imagesUri":"http://api.rovicorp.com/v1/album/images?format=json&apikey=141341&albumid=MW0002289331",
               "moods":null,
               "moodsUri":null,
               "primaryReview":null,
               "primaryReviewUri":null,
               "releases":null,
               "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 releases of the album Between the Times and the Tides. 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

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/album"
Personal tools