Gracenote Rhythm is a personalized radio API that delivers great playlists from one or more seed artists, tracks, genres, eras or moods. Playlists are generated using Gracenote's rich content descriptors that our team of editorial experts and advanced audio analysis technology provide. Radio station playlists respond to user's likes and dislikes and includes support for DMCA (Digital Millennium Copyright Act) sequencing rules.

 

The page below provides an introduction and basic getting started information. For complete Rhythm API documentation, see the following:

Rhythm API Developer's Guide and Reference

 

Your application should send Rhythm API requests to the following URL:

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

Where FORMAT can be either json or xml (we'll use JSON for all subsequent examples), and XXXXXXX is replaced with the digits of your Client ID that precede the hyphen. i.e. If you want to receive responses in JSON format, and your Client ID string is "1234567-09876543210987654321" (not a real Client ID), then you would send requests to

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

 

You must provide a User ID for all calls to Gracenote Service APIs. To get a User ID, call

 

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/register?client=CLIENT_ID

where CLIENT_ID is your assigned Client ID from your "My Apps" page.

 

One of the easiest ways to create a radio station is with an Artist's name. The following call creates a radio station using an 'Arctic Monkeys' seed:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/create?artist_name=arctic+monkeys&client=CLIENT_ID&user=USER_ID

Response (truncated)

{
    "RESPONSE": [
        {
            "STATUS": "OK",
            "RADIO": [
                {
                    "ID": "e12e7df5859fe24a907c1fcf97066bc4"
                }
            ], 
            "ALBUM": [
                {
                    "ARTIST": [
                        {
                            "VALUE": "Arctic Monkeys"
                        }
                    ], 
                    "GN_ID": "130541587-2D3C9C9035B9700747C2E71BBCA9A0FC", 
                    "ORD": "1", 
                    "TITLE": [
                        {
                            "VALUE": "Favourite Worst Nightmare"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "130541588-A1BC53F5E0A88653AEF3FD315156190D", 
                            "TITLE": [
                                {
                                    "VALUE": "Brainstorm"
                                }
                            ], 
                            "TRACK_NUM": "1"
                        }
                    ], 
                    "TRACK_COUNT": "13"
                }, 
                {
                    "ARTIST": [
                        {
                            "VALUE": "Editors"
                        }
                    ], 
                    "GN_ID": "80366086-40857F36CEEDCD84EF14F41534C4A777", 
                    "ORD": "2", 
                    "TITLE": [
                        {
                            "VALUE": "The Back Room"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "80366088-345F05FC6391628D3F4DDC1F133A1F05", 
                            "TITLE": [
                                {
                                    "VALUE": "Munich"
                                }
                            ], 
                            "TRACK_NUM": "2"
                        }
                    ], 
                    "TRACK_COUNT": "11"
                }
            ]
        }
    ]
}

 

The above call returns a RADIO ID and the first five tracks to play (only 2 are shown in the example for brevity). You'll need the RADIO ID to advance the play queue and send feedback to further personalize the station.

 

The Gracenote data model may include an ARTIST element at either the ALBUM or TRACK level. For example, on a compilation ALBUM, the ARTIST in the ALBUM element may be "Various Artists", but inside the TRACK element the ARTIST may be the individual performer of that track. Best practices for working with Gracenote data is to check for the ARTIST in the TRACK element first, and if none are found, then fall back to the ALBUM element.

 

To create a station based on a track, just specify the "track_title" parameter in conjunction with the "artist_name", for example:

 

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/create?artist_name=led+zeppelin&track_title=black+dog&client=CLIENT_ID&user=USER_ID

You will receive a playlist of tracks in the same format as the Artist station above.

 

You can also create radio stations based on musical attributes, like Genre (such as Electronica or Alternative), Mood (such as Sophisticated, or Sensual), or Era (such as 1980's or 1960's). To see the list of options available for each attribute, you first need to call the 'fieldvalues' API:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/fieldvalues?fieldname=ATTRIBUTE&client=CLIENT_ID&user=USER_ID

Where ATTRIBUTE = RADIOGENRE, RADIOMOOD, or RADIOERA This returns a set of attributes, each with an ID and a name, as in this (truncated) response:

 

Response

{
    "RESPONSE": [
        {
            "STATUS": "OK",
            "MOOD": [
                {
                    "ID": "65322", 
                    "VALUE": "Peaceful"
                }, 
                {
                    "ID": "65323", 
                    "VALUE": "Romantic"
                }, 
                {
                    "ID": "65324", 
                    "VALUE": "Sentimental"
                }
            ]
        }
    ]
}

 

To create a radio station, use the desired attribute's ID with the genre, mood, or era parameter when making a radio/create API call. You may combine up to one genre, one mood, and one era in the same query, such as in this example, which creates a radio station for "1990's, Sentimental, Indie Rock".

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/create?genre=35287&mood=65324&era=29484&client=CLIENT_ID&user=USER_ID

 

Response (truncated)

{
    "RESPONSE": [
        {
            "ALBUM": [
                {
                    "ARTIST": [
                        {
                            "VALUE": "Trashcan Sinatras"
                        }
                    ], 
                    "GN_ID": "7354762-DC47A71888C447B903FDD1FEC0D7137D", 
                    "ORD": "1", 
                    "TITLE": [
                        {
                            "VALUE": "I've Seen Everything"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "7354767-5E7A005790D238B78B102F2A0DE5FD9A", 
                            "TITLE": [
                                {
                                    "VALUE": "The Perfect Reminder"
                                }
                            ], 
                            "TRACK_NUM": "5"
                        }
                    ], 
                    "TRACK_COUNT": "14"
                }, 
                {
                    "ARTIST": [
                        {
                            "VALUE": "Mary Lou Lord"
                        }
                    ], 
                    "GN_ID": "7935475-2862207B6B6DD3568D888CD77EAD461B", 
                    "ORD": "2", 
                    "TITLE": [
                        {
                            "VALUE": "Mary Lou Lord"
                        }
                    ], 
                    "TRACK": [
                        {
                            "GN_ID": "7935483-009D362AB506168DF6646E013EAFE72A", 
                            "TITLE": [
                                {
                                    "VALUE": "Speeding Motorcycle"
                                }
                            ], 
                            "TRACK_NUM": "8"
                        }
                    ], 
                    "TRACK_COUNT": "8"
                }
             ], 
            "RADIO": [
                {
                    "ID": "9444ff8e089819d385d54efd3b140162"
                }
            ], 
            "STATUS": "OK"
        }
    ]
}

Note that using certain combinations of Genre, Mood and Era may limit the number of results you receive.

 

The IDs and values of the Gracenote attributes are region-specific (e.g. what is considered "World Music" by one country may be "Traditional" in another) To specify which regional attribute system you want, you can use the 'country' parameter when calling the 'fieldvalues' method, with country codes as defined in ISO 3166-1 alpha 3, such as 'usa' for USA, and 'jpn' for Japan. For example, to see available Genre stations for the Japan region, you would use:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/fieldvalues?country=jpn&fieldname=RADIOGENRE&client=CLIENT_ID&user=USER_ID

To change the language of all API responses (for available languages), use the 'lang' parameter 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 see available Mood stations in French, you would use:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/fieldvalues?lang=fre&fieldname=RADIOMOOD&client=CLIENT_ID&user=USER_ID
Parameter Values Default Description
focus_similarity Integer between 0 and 1000 1000 (Most similar) Controls how similar the songs in the station are to the seed artist or seed track (does not apply to attribute radio stations), where 0 is least similar, and 1000 is most similar
focus_popularity Integer between 0 and 1000 1000 (Most popular) Controls the popularity of the songs in the station, where 0 is least popular, and 1000 is most popular
dmca {yes,no} no Setting dmca to 'yes' will instruct the API to prevent tracks from the same artist from being returned more often than is allowed by DMCA rules.
DMCA rules cannot be changed after the station is created. DMCA must be specified when the station is created.
return_count Integer 5 Specifies how many tracks to return with each call to the station
select_extended {cover,link} None 'cover' will include a link to the album cover art for each track returned by the station. 'link' will include external ID's for interacting with 3rd party services with each track returned by the station (Availability of external ID's are dependent on the level of entitlement of the Client ID used). Multiple values for this parameter may be specified by using a comma separator.
lang 3 letter ISO 639-2 language code eng (English) Sets the language of the response (for available languages)
country 3 letter ISO 3166-1 alpha 3 country code usa Selects a regional-specific attribute system (for available regions)

 

 

Because the API is an personalized radio service, your application is expected to notify the API whenever a user event has taken place. A user event may be when a track is played or skipped, or a track or artist is liked or disliked. The API will respond in different ways to different user events. The available event types are:
track_played - track marked as played. Moves the play queue (drops track being played and adds additional track to end of queue)

track_skipped - track marked as skipped. Moves the play queue.

track_like - track marked as liked. Does not move the play queue.

track_dislike - track marked as disliked. Refreshes the playlist queue.

artist_like - artist marked as liked. Does not move the play queue.

artist_dislike - artist marked as disliked. Refreshes the playlist queue.

 

A successful call returns a success status and a new set of tracks depending on the feedback. For example, if you create a station and receive the first five tracks in the play queue, and then send a track_played event for the first track, you will receive back 5 tracks: tracks 1-4 will be what was previously 2-5, and track 5 will be a new track (e.g., the play queue is “moved up by one”).

 

Disliking an artist or track will refresh the entire queue to take into account the dislike event. Along with one of the above types of feedback, you need to include the track's GN_ID (which you should have from one of the radio create calls) and the track GN_ID, for example 12345-ABCDEF:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/event?radio_id=RADIO_ID&event=track_played_12345-ABCDEF&client=CLIENT_ID&user=USER_ID

You can also send multiple events in one call. Here is how you would tell the API that a user disliked track 12345-ABCDEF and also skipped it:

https://cXXXXXXX.web.cddbp.net/webapi/json/1.0/radio/event?radio_id=RADIO_ID&event=track_dislike_12345-ABCDEF;track_skipped_12345-ABCDEF&client=CLIENT_ID&user=USER_ID

 

For complete details on the Rhythm API and advanced topics like Look Ahead, Recommendations, and XML options, please see the following

> Rhythm API Developer's Guide and Reference