Gracenote Rhythm Web API Reference · Gracenote Rhythm Web API Reference Product Version 1.0 Published: 18-Feb-2014 11:04 Gracenote, Inc. 2000 Powell Street, Suite 1500 Emeryville,

Gracenote Rhythm Web API Reference

Product Version 1.0

Published: 18-Feb-2014 11:04

Gracenote, Inc.

2000 Powell Street, Suite 1500

Emeryville, California

94608-1804

www.gracenote.com

http://www.gracenote.com

Confidential Gracenote Rhythm Web API Reference

© 2000 to present. Gracenote, Inc. All rights reserved. Page of 2 23

Table of ContentsIntroduction ______________________________________________________________________________________ 3Basic Web API usage ______________________________________________________________________________ 3

Web Responses ________________________________________________________________________________ 4Radio Station Persistence __________________________________________________________________________ 4REGISTER - User Registration _____________________________________________________________________ 4

User Registration Response ______________________________________________________________________ 5FIELDVALUES (Genre, Era and Mood Reference Values for Creating a Station) __________________________ 5

Regional Specifications __________________________________________________________________________ 6FIELDVALUES Responses _______________________________________________________________________ 6

RADIO_CREATE _________________________________________________________________________________ 7Creating an Attribute Radio Station ________________________________________________________________ 8Creating a Radio Station Using an Artist Name ______________________________________________________ 8Creating a Radio Station Using Track Title __________________________________________________________ 9Creating a Radio Station Using Track GN_ID ________________________________________________________ 9Creating a Radio Station Using Multiple Seeds _____________________________________________________ 10Specifying How Many Tracks are Returned ________________________________________________________ 11RADIO_CREATE Responses ____________________________________________________________________ 12

Setting Tuning Parameters for Radio Stations ________________________________________________________ 13Query Options for Response Content _______________________________________________________________ 14RADIO_LOOKAHEAD (See What is in the Playlist Queue) ____________________________________________ 16

RADIO_LOOKAHEAD Responses ________________________________________________________________ 16RADIO_EVENT (Getting More Tracks or New Playlist) ________________________________________________ 17

Liking a Track Feedback Event ___________________________________________________________________ 17Disliking a Track Feedback Event ________________________________________________________________ 18Skipping a Track Feedback Event ________________________________________________________________ 18Playing a Track Feedback Event _________________________________________________________________ 18RADIO_EVENT Responses ______________________________________________________________________ 19

RADIO_SETTING (Additional Way to Get and Set Tuning Parameters) __________________________________ 20RADIO_RECOMMEND (Getting a Playlist Without a Radio Station) _____________________________________ 21



IntroductionThe Gracenote Rhythm APIs provide a suite of Adaptive Radio and Recommendation features in a convenientweb service.

Key features of the Gracenote Rhythm APIs:

Creates highly-relevant and personalized adaptive radio experiences and recommendations for end-usersDelivers radio stations or playlists from seed artist(s) and track(s), or a combination of genre, era, andmoodRadio stations respond to user's likes and dislikes and includes support for DMCA (Digital MillenniumCopyright Act) sequencing rulesExtends the Gracenote Music Web API that, among other rich features, supports the retrieval of cover artand 3rd-party links, and exploring metadata contentSupports REST and XML queries, and XML and JSON responses

The Gracenote Rhythm API contains the following basic query command calls (XML notation). This documentdetails these calls and provides examples of their use.

: Registers a user and returns a User ID. Each application user should haveREGISTER (see page 4)their own User ID.

: Retrieves reference values for genre, mood and era. These values canFIELDVALUES (see page )be used as configuration options for the RADIO_CREATE query command call.

: Creates and returns a playlist for a new radio station and a Radio ID.RADIO_CREATE (see page 7): Returns the current track playlist.RADIO_LOOKAHEAD (see page 16)

: Sends feedback about playlist tracks. Feedback could add a new playlistRADIO_EVENT (see page 17)track or generate a new playlist altogether.

: Configures your station's similarity and popularity settings.RADIO_SETTING (see page 20): Very similar to a RADIO_CREATE call in format. It returns aRADIO_RECOMMEND (see page 21)

playlist but does not create a radio station.

Basic Web API usageIn their default form, Gracenote Web API queries consist of well-formed XML documents HTTPS POST-ed tothe client-specific URL:

POST to https://c< >.web.cddbp.net/webapi/json/1.0/XXXXXXX

For Gracenote Rhythm, the API also supports REST calls using HTTP GET:

GET to https://c< >.web.cddbp.net/webapi/json/1.0/radio/createXXXXXXX



where

is your Client ID that precedes the hyphen (e.g. of -abcdefghijk)<XXXXXXX> 123456 123456

Web ResponsesEach query generates a JSON or XML response as specified in the base URL structure:

: < >. < >/1.0Base URL https://c XXXXXXX web.cddbp.net/webapi/ (http://web.cddbp.net/webapi/) format

where

is replaced with the digits of your Client ID that precede the hyphen (e.g. of <XXXXXXX> 123456 123456-abcdefghijk)< > = xml or jsonformat

Radio Station PersistenceOnce created, a radio station persists until it auto-expires. 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.

When you create a radio station with the RADIO_CREATE call, you get back an identifier for that station. If, in subsequent calls, you get a"No Match" response, this could be an indication that your radio station has expired and you should create a new one. However, it couldalso mean, as the message suggests, your query did not return any matches or your radio ID was not properly specified.

REGISTER - User RegistrationBefore creating and using stations, your application must first register a user(s) with the Gracenote Service. Todo this, use the REGISTER query command call and include the Client ID that you need to get from GracenoteGlobal Support Services (GGSS). Optionally, your application can include a 3 party user identifier to enablerd

linking of user accounts.

Important

Your application should create a unique User ID for each end user. This is necessary to store radio information per end user, and toenable future features, such as additional personalization. The User ID is in all subsequent calls affecting a radio station.required

XML POST example

<QUERIES>

<QUERY CMD="REGISTER">

<CLIENT>Your Client ID</CLIENT>

</QUERY>

</QUERIES>

https://c

http://web.cddbp.net/webapi/



REST API example

GET /webapi/xml/1.0/register&client=ClientID

XML POST example using 3rd Party ID

<QUERIES>

<QUERY CMD="REGISTER">


<APP_USERID>3rd Party ID</APP_USERID>

</QUERY>

</QUERIES>

REST API example using 3rd Party ID

GET /webapi/xml/1.0/register?client=ClientID&app_userid=3rdPartyID

User Registration ResponseThe Gracenote Service returns a response containing your User ID:

<RESPONSES>

<RESPONSE STATUS="OK">

<USER>Response User ID</USER>

</RESPONSE>

</RESPONSES>

FIELDVALUES (Genre, Era and Mood ReferenceValues for Creating a Station)FIELDVALUES can be used to retrieve reference values for genre, mood and era that you can use whencreating a radio station. These numeric string values are identifiers for Gracenote-defined genres, moods anderas.The options for retrieving values are:

RADIOGENRE - retrieves all genre valuesRADIOERA - retrieves all era valuesRADIOMOOD - retrieves all mood values

The examples below retrieve era reference values.

XML POST example:



<QUERIES>

<AUTH>


<USER>Your User ID</USER>

</AUTH>

<QUERY CMD="FIELDVALUES">

<FIELDNAME>RADIOERA</FIELDNAME>

</QUERY>

</QUERIES>

REST API example:

GET /webapi/xml/1.0/radio/fieldvalues?fieldname=RADIOERA&client=ClientID&user=UserID

Regional SpecificationsField values can also be returned for a specified language and region. By default, language is set to " "eng

(English) and the country is set to " ". Country codes are defined in usa ISO (International Standardsand language codes in Organization) 3166-1 alpha-3 (http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) ISO 639-2 (

. For Japan, both codes would be ' '.http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) jpn

This example retrieves field values for a specified language and region (country):

<QUERIES>

<AUTH>



</AUTH>

<LANG>eng</LANG>

<COUNTRY>usa</COUNTRY>

<QUERY CMD="FIELDVALUES">

<FIELDNAME>RADIOERA</FIELDNAME>

</QUERY>

</QUERIES>

GET /webapi/xml/1.0/radio/fieldvalues?fieldname=RADIOGENRE&country=jpn&lang=jpn&client=ClientID&user=UserID

The FIELDVALUES call returns reference values that vary depending on the country specified. If you specify a country for FIELDVALUES,then you should also specify the same country when using the resulting reference values in RADIO_CREATE to ensure the desired stationis created.

FIELDVALUES ResponsesA successful response returns the names/IDs for the attribute you request.

The following is an example response for a RADIOERA query:

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3


http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes





<RESPONSES>


<ERA ID="29483">2000's</ERA>

<ERA ID="29484">1990's</ERA>

<ERA ID="29485">1980's</ERA>

<ERA ID="29486">1970's</ERA>

<ERA ID="29487">1960's</ERA>

<ERA ID="29488">1950's</ERA>

<ERA ID="29489">Earlier</ERA>

</RESPONSE>

</RESPONSES>

RADIO_CREATEThe RADIO_CREATE query command call creates a new radio station and a playlist generated using one ormore seed items. Seed items for a radio station can include artist, track, mood, era, and genre.

This call requires a Client ID and a User ID. By default, 5 tracks are returned, unless you use the optional parameter to request 1-25 tracks.return_count

Creating a radio station returns a radio ID and a track playlist. You need the radio ID for subsequent actions onthe radio, its track playlist, or on the tuning parameters that affect a radio’s playlist generation.

You can set parameters ( , popularity, similarity) when creating a radio station; for moretuning DMCA (http://en.wikipedia.org/wiki/DMCA)information, see the section. Popularity and similarity can also be adjusted after a radio station isTuning Parameters (see page )created.

Digital Millenium Copyright Act (DMCA)

When creating a radio station, you have the option to enable DMCA rules, which reduce the repetition of songsand albums in conformance with DMCA guidelines. By default, DMCA is not enabled. Please see the Tuning

section for details. DMCA is the only tuning parameter that cannot be changed afterParameters (see page )a radio station is created.

Country and Language Parameters

The RADIO_CREATE call can take COUNTRY and LANG (language) parameters. The LANG parameterdetermines the display text to return. As a best practice, all RADIO_CREATE calls should include theseparameters. If you do not pass these parameters then, by default, English (' ') and USA (' ') are used.eng usa

Country codes are defined in ISO (International Standards Organization) 3166-1 alpha-3 (and language codes in http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) ISO 639-2 (

. For Japan, both codes would be 'jpn'.http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes)

http://en.wikipedia.org/wiki/DMCA









XML REST

<COUNTRY>[country code]</COUNTRY> or ...&country=[country code]

<LANG>[language code]</LANG> or ...&lang=[language code]

Creating an Attribute Radio StationYou have the option to create what is called an radio station using a reference value(s) for genre, mood,attributeor era. You can get reference values using a call. Note that the COUNTRYFIELDVALUES (see page )parameter specifies the genre system to access; for example, the "POP" category for Japan will be different thanthe "POP" category for the USA.

Examples of creating attribute stations (REST)

/webapi/json/1.0/radio/create?genre=12345567&country=usa&client=ClientID&user=UserID

/webapi/json/1.0/radio/create?era=12345567&country=usa&client=ClientID&user=UserID

/webapi/json/1.0/radio/create?mood=12345567&country=usa&client=ClientID&user=UserID

/webapi/json/1.0/radio/create?genre=123&era=234&mood=345&country=usa&client=ClientID&user=UserID // Only

one of each type can be used in combination

You can specify one value each for , , and . They are combined to form one attribute seed. Forgenre era mood

example, if era is the 1980's and the genre is Pop, then the resulting station is 1980's Pop.

Creating a Radio Station Using an Artist NameThis example creates a radio station using artist name as a seed.

XML POST example

<QUERIES>

<AUTH>



</AUTH>

<QUERY CMD="RADIO_CREATE">

<SEED TYPE=”TEXT”>

<TEXT TYPE=”ARTIST”>Led Zeppelin</TEXT>

</SEED>

<SEED TYPE="TEXT">

<TEXT TYPE=”ARTIST”>Pink Floyd</TEXT>

</SEED>

</QUERY>

</QUERIES>

REST API example



In the REST API, you can specify only once. To create a radio station using the REST API andartist_name

multiple seeds, see .Creating a Radio Station Using Multiple Seeds (see page 10)

GET /webapi/json/1.0/radio/create?artist_name=led+zeppelin&client=ClientID&user=UserID

Creating a Radio Station Using Track TitleThis example creates a radio station based on artist and track text. These two parameters together create asingle seed, and multiple seeds can be specified.

Example Using XML POST

<QUERIES>

<AUTH>



</AUTH>


<SEED TYPE="TEXT">

<TEXT TYPE="ARTIST">Led Zeppelin</TEXT>

<TEXT TYPE="TRACK">Black Dog</TEXT>

</SEED>

<SEED TYPE="TEXT">

<TEXT TYPE="ARTIST">Metallica</TEXT>

<TEXT TYPE="TRACK">Master of Puppets</TEXT>

</SEED>

</QUERY>

</QUERIES>

REST API example

In the REST API, you can specify and only once. To create a radio station usingartist_name track_title

the REST API and multiple seeds, see .Creating a Radio Station Using Multiple Seeds (see page 10)

GET

/webapi/json/1.0/radio/create?artist_name=led+zeppelin&track_title=black+dog&client=ClientID&user=UserID

Creating a Radio Station Using Track GN_IDThis example creates a radio station using one or more Track GN_IDs (Gracenote identifiers). Each track isconsidered one seed. You can get track GN_IDs from previous playlist generation calls.

Example Using XML POST

<QUERIES>

<AUTH>





</AUTH>


<SEED TYPE="TRACK">

<GN_ID>225260983-5E69985883A14D0975042503074BD118</GN_ID>

</SEED>

<SEED TYPE="TRACK">

<GN_ID>7433624-B0FA4A57C073E66116406B3D64396D68</GN_ID>

</SEED>

</QUERY>

</QUERIES>

REST API example

On the REST API call, you can specify multiple track GN_IDs, separated by semicolons:

GET

/webapi/xml/1.0/radio/create?track=7321567-D9CE90EB29485B85C8A2D400D9FF86EE;7393670-2540F8FD82D21BBB8F1082EEB1EC11C7&client=ClientID&user=UserID

Creating a Radio Station Using Multiple SeedsYou can create a multiple seed station to get a station with a greater variety of results.

Limitations on Using Multiple Seeds

A maximum of 5 seeds may be used to create a station.Genre, era and mood can be specified only once each. They are combined together as one attributeseed. For example, if your era is the 1980's and your genre is Pop, then your created station is 80's Pop.

Seeds act as union operators, not intersection operators. That is, they expand your possible result set, they do not filter or limit it.

XML POST example

<QUERIES>

<AUTH>



</AUTH>




<TEXT TYPE=”TRACK”>Black Dog</TEXT>

</SEED>


<TEXT TYPE=”ARTIST”>Aerosmith</TEXT>

</SEED>

</QUERY>

</QUERIES>

REST API example



In the REST API, there are some limitations on how seeds can be represented. Namely, the andartist_name

parameters can each be specified only once. We offer another way to specify multiple seeds intrack_title

REST to get around these limitations. The 'seed' parameter accepts a semicolon delimited list of values.

Value Example Notes

text_artist_{artistname}

text_artist_led+zeppelin Each text_artist by itself is considered 1 seed.

This is two seeds: &seed=text_artist_led+zepellin;text_artist_metallica

text_track_{tracktitle}

text_track_black+dog text_track requires the use of text_artist. When text_track follows

text_artist, these two values are grouped together as a seed.

Each text_artist and text_track pair is considered 1 seed.

This is two seeds:

&seed=text_artist_led+zeppelin;text_track_black+dog;text_artist_metallica;text_track_one

era_{era id}

genre_{genre id}

mood_{mood_id}

era_123

genre_222

mood_33

Each of these attributes can be specified only once.These three values grouped together is considered one seed.

&seed=era_123;genre_222;mood_33 is equivalent to specifying &era=123&

genre=222&mood=33

track_{GN_ID} track_7433624-B0FA4A57C073E66116406B3D64396D68

Multiple tracks may be specified

&seed=track_7433624-B0FA4A57C073E66116406B3D64396D68;track_225260983-5E69985883A14D0975042503074BD118

This is equivalent to:&track=225260983-5E69985883A14D0975042503074BD118;7433624-B0FA4A57C073E66116406B3D64396D68

REST API example

GET

/webapi/json/1.0/radio/create?seed=text_artist_led+zeppelin&text_track_black+dog&text_artist_aerosmith&client=ClientID&user=UserID

Specifying How Many Tracks are ReturnedThe RADIO_CREATE query command call has a RETURN_COUNT option to retrieve more, or less, than thedefault 5 tracks. The range for RETURN_COUNT is 1-25.

RETURN_COUNT is also an optional parameter with the RADIO_LOOKAHEAD, RADIO_EVENT, andRADIO_SETTING query command calls.

XML POST example

<QUERIES>

<AUTH>



</AUTH>




<SEED TYPE="TEXT">

<TEXT TYPE="ARTIST">Led Zeppelin</TEXT>

</SEED>

<OPTION>

<PARAMETER>RETURN_COUNT</PARAMETER>

<VALUE>10</VALUE>

</OPTION>

</QUERY>

</QUERIES>

REST API example

GET /webapi/xml/1.0/radio/create?artist_name=led+zeppelin&client=ClientID&user=UserID&return_count=10

RADIO_CREATE ResponsesBelow is an example of an XML response to a successful RADIO_CREATE command query call. Yourapplication should save the radio’s unique ID (<RADIO><ID> </ID></RADIO>) returned in theXXXXXXXresponse. This Radio ID can be used at a later time to resume the current radio session starting at the trackwhere it left off. Returned with each track is its unique Gracenote ID (GN_ID). You can use a GN_ID later as aparameter for a feedback event call (RADIO_EVENT) indicating that a track has been played, skipped, disliked,liked and so on. It can also be used as a seed to create a new radio station.

<RESPONSES>




<RADIO>

<ID>Radio ID</ID> 

</RADIO>



<ALBUM ORD="1">

<GN_ID>7286646-4E6F2826F10FDDC14E358050AB130032</GN_ID>

<ARTIST>The Beatles</ARTIST>

<TITLE>Abbey Road</TITLE>

<TRACK>

<GN_ID>7286647-0D4F7CB2CE2C57A95398CA34EA411CBD</GN_ID>

<TITLE>Come Together</TITLE>

<XID DATASOURCE="3rdpartyname">123456</XID>

</TRACK>

<URL TYPE="COVERART" SIZE="MEDIUM">https://web.content.cddbp...</URL>

</ALBUM>

<ALBUM ORD="2">

<GN_ID>2898160-036A68093B4188CAB2BF28CDBB074410</GN_ID>

<ARTIST>The Doors</ARTIST>

<TITLE>Waiting For The Sun</TITLE>

<TRACK>

<GN_ID>246800629-50746A3DF3407A94D936F56DCB2E19FE</GN_ID>

<TITLE>Hello, I Love You</TITLE>



<XID DATASOURCE="3rdpartyname ">234567</XID>

</TRACK>

<URL TYPE="COVERART" SIZE="MEDIUM">https...</URL>

</ALBUM>

<ALBUM ORD="3">

...clipped...

</ALBUM>

<ALBUM ORD="4">

...clipped...

</ALBUM>

<ALBUM ORD="5">

...clipped...

</ALBUM>

</RESPONSE>

</RESPONSES>

Setting Tuning Parameters for Radio StationsWhen making a RADIO_CREATE query command call, your application can specify tuning parameters thataffect how a radio station playlist is generated. After creating a radio station, you can change the tuningparameters when making a RADIO_EVENT query command call. The following options are supported for boththe RADIO_CREATE and RADIO_EVENT command calls.

Similarity applies only to artist or track seeded stations; it does not apply to attribute stations (genre, mood and era). Popularity applies toall station types.

Name XML Example REST URL Example Values Default

Popularity<OPTION>

<PARAMETER>FOCUS_POPULARITY</PARAMETER>

<VALUE>76</VALUE>

</OPTION>

focus_popularity=76 0 .. 1000 1000 (most popular)

Similarity<OPTION>

<PARAMETER>FOCUS_SIMILARITY</PARAMETER>

<VALUE>5</VALUE>

</OPTION>

focus_similarity=5 0 .. 1000 1000 (most similar)

DMCA<OPTION>

<PARAMETER>DMCA</PARAMETER>

<VALUE>YES</VALUE>

</OPTION>

dmca=yes yes, no no

XML POST example - This will create a radio station with FOCUS_POPULARITY set to 500, and DMCA on.



<QUERIES>

<AUTH>



</AUTH>




</SEED>

<OPTION>


<VALUE>500</VALUE>

</OPTION>

<OPTION>


<VALUE>YES</VALUE>

</OPTION>

</QUERY>

</QUERIES>

REST API example

GET

/webapi/xml/1.0/radio/create?artist_name=led+zeppelin&client=ClientID&user=UserID&focus_popularity=500&dmca=yes

Query Options for Response ContentWhen sending a radio query, a few options can be set that control the response. The following settings areappropriate for RADIO_CREATE, RADIO_SETTINGS, RADIO_EVENT or RADIO_LOOKAHEAD.

Option Default Description

RETURN_COUNT

XML example:

<OPTION> <PARAMETER>RETURN_COUNT</PARAMETER>

<VALUE>6</VALUE></OPTION>

REST example

&return_count=6

5 Specifies how many tracks to return in the playlist response tothis query.The default value is 5. The range for this parameter is 1-25.

SELECT_EXTENDED

XML example:<OPTION><PARAMETER>SELECTED_EXTENDED</PARAMETER><VALUE>COVER,LINK</VALUE></OPTION>

REST example:

&select_extended=cover,link

none Specifies extra data to return for the albums and tracks thatmake up the playlist.

Available choices:

COVER

ARTIST_IMAGE

LINK

MOOD



TEMPO

Note that cover art is only returned for the first 5 tracks.

When multiple values are used, they should be commaseparated with no spaces.

RETURN_SETTINGS

XML example:

<OPTION>

<PARAMETER>RETURN_SETTINGS</PARAMETER>

<VALUE>YES</VALUE>

</OPTION>

REST example:

&return_settings=yes

NO Returns the current values of the tunable parameters in theradio response, such as

, , DMCA FOCUS_POPULARITY FOCUS_SIMILARITY

Example:"RESPONSE":[{"STATUS" : "OK","RADIO":[{"ID" : "343b73bb8789ea27fcb39c96874c5511","OPTION":[{"PARAMETER" : "DMCA","VALUE" : "YES"},{"PARAMETER" : "FOCUS_SIMILARITY","VALUE" : "1000"},{"PARAMETER" : "FOCUS_POPULARITY","VALUE" : "500"}]}], … rest of response albums, etc

RETURN_GNUIDS

XML example:<OPTION><PARAMETER>RETURN_GNUIDS</PARAMETER><VALUE>YES</VALUE></OPTION>

REST example:

&return_gnuids=yes

NO Returns GNUID in addition to GN_ID. GNUIDs are anotheridentifier used insome other Gracenote products.

FALLBACK_GENRECOVER

XML example:<OPTION><PARAMETER>FALLBACK_GENRECOVER</PARAMETER<VALUE>YES</VALUE></OPTION>

REST example:

&fallback_genrecover=yes

NO Returns generic genre coverart in cases where album-specificcoverart is not available.

Requires SELECT_EXTENDED contains COVER



COVER_SIZE

XML example:<OPTION><PARAMETER>COVER_SIZE</PARAMETER><VALUE>LARGE</VALUE></OPTION>

REST example:

&cover_size=large

medium Specifies preferred cover size.

Can specify multiple sizes comma-seperated; the earliest oneon the list that can befulfilled will be the size returned.

available sizes: thumbnail, small, medium, large, xlarge

RADIO_LOOKAHEAD (See What is in the PlaylistQueue)Use the RADIO_LOOKAHEAD command query call to retrieve the tracks in the current playlist. For example,when a radio station is re-instantiated after non-use, its usage can be resumed using RADIO_LOOKAHEAD toretrieve the queue of tracks that were in play.

Repeated RADIO_LOOKAHEAD command calls retrieve the same track list. To retrieve additional tracks or a new playlist, use theRADIO_EVENT call.

XML POST example

<QUERIES>

<AUTH>



</AUTH>

<QUERY CMD="RADIO_LOOKAHEAD">

<RADIO>

<ID>Radio ID</ID>

</RADIO>

</QUERY>

</QUERIES>

REST API example

GET /webapi/xml/1.0/radio/lookahead?radio_id=RadioID&client=ClientID&user=UserID

RADIO_LOOKAHEAD ResponsesThe output from making a RADIO_LOOKAHEAD command call is the same as that from the RADIO_EVENTcall. See the RADIO_EVENT example responses below for more information.



RADIO_EVENT (Getting More Tracks or New Playlist)Use the RADIO_EVENT query command call to send Gracenote user feedback about tracks. Available feedbackevent types include (JSON):

- track marked as played. Advances the play queue by one track (drops track beingtrack_played

played and adds additional track to end of queue) - track marked as skipped. Advances the play queue by one tracktrack_skipped

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

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

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

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

Only and move the play queue. If you want the play queue to move on a event, youtrack_played track_skipped track_dislike

need to send two events: and . Multiple events can be sent in the same call.track_dislike track_skipped

Disliking a artist or track will refresh the queue, and return a new set of tracks. The new queue will takeinto account the dislike event.Along with one of the above types of feedback, you need to include the GN_ID of the affected track,which you should have from one of the generate playlist calls. See below for examples.

With each successful RADIO_EVENT response a new set of tracks is returned that reflects the current queue, which has taken intoaccount the feedback provided. Your application should use this response to update its track list.

Liking a Track Feedback EventThe example below provides feedback indicating that the user likes a track.

XML POST example

<QUERIES>

<AUTH>



</AUTH>

<QUERY CMD="RADIO_EVENT">

<RADIO>

<ID>AHFBJKFHJDFHSDJKFHS</ID>

</RADIO>

<EVENT TYPE="TRACK_LIKE">



<GN_ID>225260983-5E69985883A14D0975042503074BD118</GN_ID>

</EVENT>

</QUERY>

</QUERIES>



REST API example

GET

/webapi/xml/1.0/radio/event?radio_id=RadioID&event=track_like_225260983-5E69985883A14D0975042503074BD118&client=ClientID&user=UserID

Disliking a Track Feedback EventThe example below shows feedback indicating that the user dislikes a track.

XML POST example

...

<EVENT TYPE="TRACK_DISLIKE">



<GN_ID>225260983-5E69985883A14D0975042503074BD118</GN_ID>

</EVENT>

...

REST API example

GET /webapi/xml/1.0/radio/event?radio_id=RadioID&event=track_dislike_GN_ID&client=ClientID&user=UserID

Skipping a Track Feedback EventThe example below shows feedback indicating that the user skipped a track.

XML POST example

...

<EVENT TYPE="TRACK_SKIPPED">



<GN_ID>225260983-5E69985883A14D0975042503074BD118</GN_ID>

</EVENT>

...

REST API example

GET /webapi/xml/1.0/radio/event?radio_id=RadioID&event=track_skipped_<GN_ID>&client=ClientID&user=UserID

Playing a Track Feedback EventThe example below shows feedback indicating that the user played a track.

XML POST example



...

<EVENT TYPE="TRACK_PLAYED">



<GN_ID>225260983-5E69985883A14D0975042503074BD118</GN_ID>

</EVENT>

...

REST API example

GET /webapi/xml/1.0/radio/event?radio_id=RadioID&type=track_skipped_<GN_ID>&client=ClientID&user=UserID

RADIO_EVENT ResponsesSuccessful feedback can result in two different types of responses. The simplest response is a GracenoteService acknowledgement that does not send any new tracks:

<RESPONSES>

<RESPONSE STATUS="OK"/>

</RESPONSES>

Alternatively, based on the type of feedback, the Gracenote Service can immediately modify the radio playlistand send a new list of tracks. When the client sees a response containing a new playlist, it should delete itscurrent playlist and use the new one. The format of this type of response is identical to the RADIO_CREATEresponse:

<RESPONSES>


<RADIO>

<ID>AHFBJKFHJDFHSDJKFHS</ID>

</RADIO>

<ALBUM ORD="1">

...clipped...

</ALBUM>

<ALBUM ORD="2">

...clipped...

</ALBUM>

<ALBUM ORD="3">

...clipped...

</ALBUM>

<ALBUM ORD="4">

...clipped...

</ALBUM>

<ALBUM ORD="5">

...clipped...

</ALBUM>

</RESPONSE>

</RESPONSES>



RADIO_SETTING (Additional Way to Get and SetTuning Parameters)This call configures your station's settings for popularity (0-1000) and similarity (0-1000). 1000 means mostpopular or most similar. See for more detail.Tuning Parameters (see page )

Similarity applies only to artist or track seeded stations; it does not apply to attribute stations (genre, mood and era). Popularity applies toall station types.

XML POST example

<QUERIES>

<AUTH>...</AUTH>

<QUERY CMD="RADIO_SETTING">

<RADIO>

<ID>343b73bb8789ea27fcb39c96874c5511</ID>

</RADIO>

<OPTION>


<VALUE>111</VALUE>

</OPTION>

<OPTION>


<VALUE>222</VALUE>

</OPTION>

</QUERY>

</QUERIES>

REST API example

GET

/webapi/json/1.0/radio/setting?client=ClientID&user=UserID&radio_id=RadioID&focus_similarity=111&focus_popularity=222

In every query, you can also request that the values for popularity and similarity be returned.

You can do this with the RETURN_SETTINGS parameter. For example:

<QUERY CMD="RADIO_LOOKAHEAD">

<RADIO>

<ID>RadioID</ID>

</RADIO>

<OPTION>

<PARAMETER>RETURN_SETTINGS</PARAMETER>

<VALUE>YES</VALUE>

</OPTION>

</QUERY>

Response example




<RADIO>

<ID>RadioID</ID>

<OPTION>


<VALUE>1000</VALUE>

</OPTION>

<OPTION>


<VALUE>1000</VALUE>

</OPTION>

<OPTION>


<VALUE>NO</VALUE>

</OPTION>

</RADIO>

<!- The tracks for RADIO_LOOKAHEAD as before -->

<ALBUM>

...

</ALBUM>

...

</RESPONSE>

RADIO_RECOMMEND (Getting a Playlist Without aRadio Station)The recommendation API is very similar to RADIO_CREATE but does not create a radio station or return a radioID.

As with RADIO_CREATE, you can specify a RETURN_COUNT to return more, or less, than the default 5 tracks.The range for RETURN_COUNT is 1-25.

The following additional options are available in RADIO_RECOMMEND that are not present inRADIO_CREATE:

Name XMLExample

REST URLExample

Values Description

Maxtracksperartist

&tracks_per_artist=5 1 ..1000

Specifies a maximum number of tracks per artist for recommended playlist results

Rotation &rotation=radio radio |none

Choosing 'radio' will cause results to be sequenced in a radio-like fashion. Choosing 'none'will return normal recommendation results without sequencing. For example, ' ' mightnone

return you 5 Britney Spears tracks; ' ' would never do that, it would mix it up more, likeradio

a radio station.

The DMCA option is not available for RADIO_RECOMMEND.



XML POST example

<QUERIES>

<AUTH>

…

</AUTH>

<QUERY CMD="RADIO_RECOMMEND">

<SEED TYPE="TEXT">

<TEXT TYPE="ARTIST">Metallica</TEXT>

</SEED>

<SEED TYPE="TEXT">

<TEXT TYPE="ARTIST">Kelly Clarkson</TEXT>

</SEED>

<SEED TYPE="TRACK">

<GN_ID><Gracenote ID></GN_ID>

</SEED>

<SEED TYPE="ATTRIBUTE">

<GENRE ID="35288"/>

<ERA ID="2650"/>

<MOOD ID="65326"/>

</SEED>

<OPTION>

<PARAMETER>SELECT_EXTENDED</PARAMETER>

<VALUE>LINK,COVER,MOOD,TEMPO,ARTIST_IMAGE</VALUE>

</OPTION>

<OPTION>

<PARAMETER>COVER_SIZE</PARAMETER>

<VALUE>LARGE</VALUE>

</OPTION>

<OPTION>

<PARAMETER>RETURN_COUNT</PARAMETER>

<VALUE>25</VALUE>

</OPTION>





<OPTION>

<PARAMETER>MAX_TRACKS_PER_ARTIST</PARAMETER>

<VALUE>4</VALUE> 

</OPTION>

<OPTION>

<PARAMETER>ROTATION</PARAMETER>

<VALUE>RADIO</VALUE> 

</OPTION>

</QUERY>

</QUERIES>

REST API example

//single seed

GET

/webapi/xml/1.0/radio/recommend?artist_name=aerosmith&client=ClientID&user=UserID&max_tracks_per_artist=5

//multiple seeds



GET

/webapi/xml/1.0/radio/recommend?seed=text_artist_led+zeppelin;text_artist_aerosmith&client=ClientID&user=UserID&rotatation=radio

Documents

Gracenote Rhythm Web API Reference · Gracenote Rhythm Web API Reference Product Version 1.0 Published: 18-Feb-2014 11:04 Gracenote, Inc. 2000 Powell Street, Suite 1500 Emeryville,