Rhythm API

Music Platforms Navigation

The Gracenote Rhythm APIs provide adaptive radio and music recommendation features in a convenient Web service. 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.

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.

Getting Started

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:

Register with the Rhythm API

Create a radio station

Send Gracenote feedback about your station (modifies station playlist)

Tune your radio station (popularity, similarity, or mood)

Registering

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.

Creating a Station

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:

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

Sending Feedback

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.

Conclusion

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 90 days. 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.