The Gracenote Web API delivers a rich set of music metadata over HTTP to help power interactive experiences for any connected application. This allows text-based lookups of music artists, albums and tracks, and returns descriptive metadata such as genre, region of origin, and mood, as well as Cover Art, Artist Images, biographies, and other related content items. Additional modes of lookup such as CD or audio recognition require the use of one of Gracenote's other platforms such as GNSDK or Mobile Client.

Music Web API Developer's Guide

Facebook Open Graph Music with Gracenote Metadata

The first thing you need to do is get a Client ID - a Gracenote API key that authorizes you to make calls to the Gracenote service. To do this, you must be logged-in with your developer account. Go to the My Apps page and click on "Add a new app". Once your app is created, click on it to see the App Details. You will find your Client ID under "Client ID for Mobile Client and Web API".  

URL

Requests to the Web API should be sent to the following URL:

https://cXXXXXXX.web.cddbp.net/webapi/xml/1.0/

Where XXXXXXX is replaced with the digits of your Client ID that precede the hyphen. i.e. if your Client ID string is "1234567-09876543210987654321" (not a real Client ID), then you would send requests to

https://c1234567.web.cddbp.net/webapi/xml/1.0/

 

User Registration

Each call to the Gracenote service must be accompanied by a User ID. To register for a User ID, send the following query to the above URL:

<QUERIES>
  <QUERY CMD="REGISTER">
    <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
  </QUERY>
</QUERIES>

You should register with Gracenote once and only once per application install. If you are building a server-side app, you should register once and store the User ID for all subsequent calls. If you are building a mobile or desktop app, then each user's app should register once (for example on the first launch of the app) to get their own unique User ID, and then store this User ID and use it for subsequent calls.

Basic Track Search

Once you have your Client ID and User ID, you can use the following example query to do a basic text search using the Artist, Album & Track Name to find Genres and IDs.

Query:

<QUERIES>
  <LANG>eng</LANG>
  <AUTH>
    <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
    <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
  </AUTH>
  <QUERY CMD="ALBUM_SEARCH">
    <TEXT TYPE="ARTIST">flying lotus</TEXT>
    <TEXT TYPE="ALBUM_TITLE">until the quiet comes</TEXT>
    <TEXT TYPE="TRACK_TITLE">all in</TEXT>
  </QUERY>
</QUERIES>

 

Response:

<RESPONSES>
 <RESPONSE STATUS="OK">
   <RANGE>
      <COUNT>1</COUNT>
      <START>1</START>
      <END>1</END>
   </RANGE>
   <ALBUM ORD="1">
      <GN_ID>285989015-2071B8373D274F80A743FC03035A8E91</GN_ID>
      <ARTIST>Flying Lotus</ARTIST>
      <TITLE>Until The Quiet Comes</TITLE>
      <DATE>2012</DATE>
      <GENRE NUM="105251" ID="35497">Downtempo, Lounge & Ambient</GENRE>
      <MATCHED_TRACK_NUM>1</MATCHED_TRACK_NUM>
      <TRACK_COUNT>18</TRACK_COUNT>
      <TRACK>
         <TRACK_NUM>1</TRACK_NUM>
         <GN_ID>285989016-0F3AAEEDA9351A79C04ED7B0004C37FF</GN_ID>
         <TITLE>All In</TITLE>
      </TRACK>
   </ALBUM>
 </RESPONSE>
</RESPONSES>

 

Track search with additional attributes

This query returns more detailed information about a track. Use Ord=X to specify the level of detail to return for each descriptor type.

Query:

<QUERIES>
  <AUTH>
    <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
    <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
  </AUTH>
  <QUERY CMD="ALBUM_SEARCH">
    <MODE>SINGLE_BEST_COVER</MODE>
    <TEXT TYPE="ARTIST">flying lotus</TEXT>
    <TEXT TYPE="ALBUM_TITLE">until the quiet comes</TEXT>
    <TEXT TYPE="TRACK_TITLE">all in</TEXT>
    <OPTION>
      <PARAMETER>SELECT_EXTENDED</PARAMETER>
      <VALUE>COVER,REVIEW,ARTIST_BIOGRAPHY,ARTIST_IMAGE,ARTIST_OET,MOOD,TEMPO</VALUE>
    </OPTION>
    <OPTION>
      <PARAMETER>SELECT_DETAIL</PARAMETER>
      <VALUE>GENRE:3LEVEL,MOOD:2LEVEL,TEMPO:3LEVEL,ARTIST_ORIGIN:4LEVEL,ARTIST_ERA:2LEVEL,ARTIST_TYPE:2LEVEL</VALUE>
    </OPTION>
  </QUERY>
</QUERIES>

 

Response:

<RESPONSES>
 <RESPONSE STATUS="OK">
   <ALBUM>
      <GN_ID>285989015-2071B8373D274F80A743FC03035A8E91</GN_ID>
      <ARTIST>Flying Lotus</ARTIST>
      <ARTIST_ORIGIN ORD="1" ID="29889">North America</ARTIST_ORIGIN>
      <ARTIST_ORIGIN ORD="2" ID="29908">United States</ARTIST_ORIGIN>
      <ARTIST_ORIGIN ORD="3" ID="30170">California</ARTIST_ORIGIN>
      <ARTIST_TYPE ORD="1" ID="29422">Male</ARTIST_TYPE>
      <ARTIST_TYPE ORD="2" ID="29426">Male</ARTIST_TYPE>
      <ARTIST_ERA ORD="1" ID="29483">2000's</ARTIST_ERA>
      <ARTIST_ERA ORD="2" ID="29493">Late 2000's</ARTIST_ERA>
      <TITLE>Until The Quiet Comes</TITLE>
      <DATE>2012</DATE>
      <GENRE ORD="1" NUM="105216" ID="35470">Electronica</GENRE>
      <GENRE ORD="2" NUM="105251" ID="35497">Downtempo, Lounge & Ambient</GENRE>
      <GENRE ORD="3" NUM="62070" ID="25656">Ambient Electronica</GENRE>
      <MATCHED_TRACK_NUM>1</MATCHED_TRACK_NUM>
      <TRACK_COUNT>18</TRACK_COUNT>
      <TRACK>
         <TRACK_NUM>1</TRACK_NUM>
         <GN_ID>285989016-0F3AAEEDA9351A79C04ED7B0004C37FF</GN_ID>
         <TITLE>All In</TITLE>
         <MOOD ORD="1" ID="42960">Excited</MOOD>
         <MOOD ORD="2" ID="43053">Euphoric Energy</MOOD>
         <TEMPO ORD="1" ID="43078">Fast Tempo</TEMPO>
         <TEMPO ORD="2" ID="34292">Fast</TEMPO>
         <TEMPO ORD="3" ID="34538">140s</TEMPO>
      </TRACK>
   </ALBUM>
 </RESPONSE>
</RESPONSES>

Language Settings

To change the language of all API responses (for available languages), use the <LANG> element with any API call with a 3 letter ISO 639-2 language code (e.g. 'eng' for English, and 'jpn' for Japanese). For example, to do the previous example query in German:

<QUERIES>
  <AUTH>
    <CLIENT>XXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</CLIENT>
    <USER>XXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</USER>
  </AUTH>
  <LANG>ger</LANG>
  <QUERY CMD="ALBUM_SEARCH">
    <MODE>SINGLE_BEST_COVER</MODE>
    <TEXT TYPE="ARTIST">flying lotus</TEXT>
    <TEXT TYPE="ALBUM_TITLE">until the quiet comes</TEXT>
    <TEXT TYPE="TRACK_TITLE">all in</TEXT>
    <OPTION>
      <PARAMETER>SELECT_EXTENDED</PARAMETER>
      <VALUE>COVER,REVIEW,ARTIST_BIOGRAPHY,ARTIST_IMAGE,ARTIST_OET,MOOD,TEMPO</VALUE>
    </OPTION>
    <OPTION>
      <PARAMETER>SELECT_DETAIL</PARAMETER>
      <VALUE>GENRE:3LEVEL,MOOD:2LEVEL,TEMPO:3LEVEL,ARTIST_ORIGIN:4LEVEL,ARTIST_ERA:2LEVEL,ARTIST_TYPE:2LEVEL</VALUE>
    </OPTION>
  </QUERY>
</QUERIES>

There are also unofficial wrappers to the Web API for various languages, which abstract the XML protocol and allow text-based lookups of Artist, Album and Track metadata with the most common options.

As these are unofficial projects, Gracenote does not provide any support or warranty for them. If you have any questions or issues with using them, you should contact the author directly through the feedback mechanisms available on the repository hosting the code.

Python

PHP

Java

Ruby

ColdFusion