The Gracenote Rhythm APIs provide adaptive radio and music recommendation features in a convenient Web service.

Gracenote Rhythm APIs' key features include:

  • Adaptive Radio - Creates highly-relevant and personalized adaptive radio experiences and recommendations for end-users.
  • Playlisting - Delivers radio station or recommendation playlists from up to 5 seeds. A seed can be an artist, track, or attribute (genre, era, and mood).
  • Filtering - Filters results based on mood(s) or a music catalog. Talk to a Gracenote representative about integrating your catalog with Gracenote's database.
  • Feedback - Send Gracenote feedback about user events (track played, track disliked, etc.) which can modify a station's playlist.
  • Tuning - Tune your station's playlist according to popularity, similarity, or mood.
  • Rich Content - Supports the retrieval of cover art, 3rd-party links, and exploring metadata.
  • DMCA - DMCA stands for Digital Millenium Copyright Act. When creating a radio station, you have the option to enable DMCA rules, which reduces the repetition of songs and albums in conformance with DMCA guidelines.
  • Multi-Protocol API Support - Supports REST and XML queries, and XML and JSON responses.

The page below provides an introduction and basic getting started information. For complete Rhythm API documentation, see the Rhythm API Developer's Guide and Reference.

 

The quickest way to get familiar with the Rhythm API is to step through creating a radio station. By "radio station," we mean playlist metadata that you can adjust via feedback events or changing various settings. Note that Gracenote does not provide streaming capability for playlist tracks. For this, you can look into streaming audio providers such as 7Digital, Deezer, Spotify, Rdio, Beats Music, and others.

We could either create a station or get recommendations. Getting recommendations, however, is a one-shot, singular event - you cannot modify or adjust a recommendations playlist.

Creating and maintaining a station involves the following basic steps:

  1. Register with the Rhythm API
  2. Create a radio station
  3. Send Gracenote feedback about your station (modifies station playlist)
  4. Tune your radio station (popularity, similarity, or mood)

 

Before you begin, you need to get an authorization key known as a "Client ID/Tag" from Gracenote. This should be assigned to you from your "My Apps" page.

Example Client ID/Tag:

1234567-8DF1BF67913711DA38B26DA852B26D1A

As you can see, a Client ID/Tag is two sets of alphanumeric characters separated with a hyphen. The numbers before the hyphen constitute the "Client ID" and the numbers/letters after are the "Client Tag".

Once you have your Client ID/Tag, you are then ready to make your first call and register with the Rhythm API.

The endpoint URL for the register call is going to look like this:

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

Where you replace "XXXXXXX" with your Client ID to form your personalized URL for all Rhythm API calls. FORMAT can be either "xml" or "json" depending on your preferred response. For the purposes of this tutorial, all calls and responses are going to use JSON.

For example:

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

We can now make our register API call, which would look like this:

https://c1234567.web.cddbp.net/webapi/json/1.0/register?client=1234567-8DF1BF67913711DA38B26DA852B26D1A

This call returns a "User ID," which is required for all subsequent calls:

{
    "RESPONSE":
    [
      {
        "STATUS" : "OK",
        "USER":
        [
          {
            "VALUE" : "261581584653824776-FCB959CBCC84B6A3CCB84BEEA92BC34C"
          }
        ]
      }
    ]
}

 

Now that we have registered with the Rhythm API, we can create a radio station. This requires passing the create API a "seed" value. You can provide up to 5 seeds and they can be any combination of artist, track, attributes (genre, era, mood), or third-party external identifiers.

Here we are going to use two seeds: artist and genre. The artist is going to be "Led Zeppelin" and the genre is going to be "Blues". You specify attributes (genre, era, and mood) with Gracenote defined reference values. To find the reference value for "Blues" then, we are going to have to make a fieldvalues API call, which returns attribute values:

https://c1234567.web.cddbp.net/webapi/json/1.0/radio/fieldvalues?client=1234567-288F907CEB2B3FB67605FFCFD23052F4&user=261581584653824776-FCB959CBCC84B6A3CCB84BEEA92BC34C&fieldname=RADIOGENRE

Click here to show/hide genre metadata response

This call gives us our reference value for "Blues" (36060), so now we can create our station:

https://c1234567.web.cddbp.net/webapi/json/1.0/radio/create?artist_name=led+zeppelin&genre=36060
&client=1234567-8DF1BF67913711DA38B26DA852B26D1A&user=26833668058016863-5175F04B8402332E44918910C64EBB88

Click here to show/hide metadata response

Notice that this call returns a radio station ID (635832a2ad2b79106ce49e44991e03ca), which you will need for all subsequent API calls affecting the station.

You can use the event API call to let Gracenote know about user interactions with your station. These interactions include:

  • Track played
  • Track skipped
  • Track disliked
  • Artist liked
  • Artist disliked

Some of these events are going to result in your station's playlist queue being modified. In this call, we are going to send a track played event for the first track. The track is identified with its GNID (Gracenote ID), which can be parsed from playlist metadata.

https://c1234567.web.cddbp.net/webapi/json/1.0/radio/event?radio_id=635832a2ad2b79106ce49e44991e03ca&event=track_played_7284094-7E561B626D6158CDA8C41A05098CCECD&client=1234567-8DF1BF67913711DA38B26DA852B26D1A&user=26833668058016863-5175F04B8402332E44918910C64EBB88

The call refreshes the playlist queue - if you inspect the returned metadata (below) you will see that the first track has been removed from the queue and a new track has been added to the end.


Click here to show/hide event metadata response

 

After your station is created, you can modify the following using the setting API call:

  • Popularity - How popular your playlist tracks are on a scale of 1 to 1000 (most popular)
  • Similarity - How similar your playlist tracks are on a scale of 1 to 1000 (most similar)
  • Mood filter - You can filter your playlist with up to 25 moods

For this exercise, we are going to adjust our station for mood, specifically, melancholy (reference value = 42949):

https://c1234567.web.cddbp.net/webapi/json/1.0/radio/setting?radio_id=635832a2ad2b79106ce49e44991e03ca&filter_mood=42949&client=1234567-8DF1BF67913711DA38B26DA852B26D1A&user=26833668058016863-5175F04B8402332E44918910C64EBB88

Click here to show/hide settings metadata response

 

We hope this has given you some idea of how to use the Rhythm API. We've created a radio station and modified its playlist with user event feedback and tuning. We have used five of the seven Rhythm API calls: register, fieldvalues, create, event, and setting. For detailed information about the calls comprising the Rhythm API, you should consult the Rhythm API Developer's Guide and Reference.

Note that, once created, a radio station persists until it auto-expires after being inactive for one month. While it exists, the station's current playlist, its state, associated events, and current configuration continue to persist. Your application cannot delete a radio station.