Radio Station ID API Dev Guide

The Gracenote Radio Station ID API returns JSON metadata about radio stations from the Gracenote media database. This REST-based web API exposes the Gracenote Radio Station ID product.

The base address of the Web API is https://api.rsid.music.gracenote.com. The API provides endpoints with its own unique path. Communication is done over HTTPS and response is formatted as JSON (the content type is application/json).

Note: Only a “server-side” implementation is allowed to use Radio Station ID API.

Radio Station ID provides available local radio station data as vehicles move in and out of range, enabling products to create smart guides that visually display rich metadata, official station logos, and names. Radio Station ID covers analog and digital broadcast - AM, FM, HD and DAB.

Key Benefits

Improves Search and Navigation

Improves how drivers search for and find radio stations by providing the ability for rich imagery and normalized radio station metadata.

• Station Logos: Up-to-date, high quality station logos enable visual navigation.
• Station Name: Combined with frequency to provide for smarter menu creation.

Location-based Discovery

Offers location-based delivery of radio station metadata, including broadcast availability information.

• Automatically presents available stations based on driver's location.
• Eliminates the need for drivers to 'scan the dial' as they move outside of radio signal range.
• Provides data for recommendations to enable drivers to discover more of the radio stations they love as they drive between regions.

Getting Started

Step 1. Get Authentication Credentials

You first must get authentication credentials (client key & client secret). This key & secret pair uniquely identifies each application to Gracenote Web API Services and lets Gracenote deliver radio stations metadata that the application requires.

Each customer receives a unique set of authentication credentials from Gracenote. The client key & client Secret consists of alphanumeric characters.

• Key (example): aBC1DEf2gHI3jKL4mNO5PQr6sTu7vWX8

• Secret (example): YZa9aBC1DeF2ghi3

Step 2. Authorize - Get Access Token

Gracenote uses OAuth 2.0 for authorization of the client in server-to-server communication. OAuth 2.0 allows clients to delegate authorization by issuing an "Access Token" that grants the bearer of the token the necessary authorization to access the underlying API. Clients can use this “access token” to call the radio stations endpoint (GET /v1.1/radiostations).

After you received the authentication credentials from Gracenote, you retrieve the access token by sending a POST request to the /oauth/authorize endpoint**.**

Encode Authentication Credentials with Base64

To send a POST request, encode the authentication credential string with Base64 for the Basic Authentication Header. The authentication credential string consists of <client key> and <client secret> separated with a colon (:).

Authentication Credential String Format: <Client Key>:<Client Secret>

Example: aBC1DEf2gHI3jKL4mNO5PQr6sTu7vWX8:YZa9aB:C1DeF2ghi3

This command-line example encodes authentication credentials with Base64 on Linux/Mac OS X:

Code
 
$ printf 'aBC1DEf2gHI3jKL4mNO5PQr6sTu7vWX8:YZa9aBC1DeF2ghi3' | base64 YUJDMURFZjJnSEkzaktMNG1OTzVQUXI2c1R1N3ZXWDg6WVphOWFCQzFEZUYyZ2hpMw==

Get Access Token (POST /oauth/authorize)

Make the POST request using the Base64 Encoded Basic Authentication header.

Code
 
curl -X POST -H 'Authorization: Basic YUJDMURFZjJnSEkzaktMNG1OTzVQUXI2c1R1N3ZXWDg6WVphOWFCQzFEZUYyZ2hpMw==' -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' 'https://api.rsid.music.gracenote.com/oauth/authorize'

Response

If the client authentication is successful, the authorize endpoint (POST /oauth/authorize) will send a response in the following format:

Code
 
{
"token_type": "BearerToken", "issued_at": "1524623453941","client_id": "aBC1DEf2gHI3jKL4mNO5PQr6sTu7vWX8", "access_token": "gv4DVSpbh86XXnctAsec4DC45JMA", "expires_in": "43119",
"status": "approved"
}

Step 3. Make Your First Request

You can now make an API call by using the access_token received from the authorize endpoint (POST /oauth/authorize). Pass the access token as Authentication Bearer in the HTTP Headers when making a GET request to the radio stations endpoint (GET /v1.1/radiostations).

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?band=FM&coun  try=US&frequency=88.5&call_sign=KQED-FM"

Example Queries

Identify AM Radio Stations

Target:

• AM radio station "KNBR 680 1050" in San Francisco, California, USA
• geolocation=37.7879938,-122.407437
• country=US, frequency=680
• call_sign=KNBR cURL (with geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?b and=AM&geolocation=37.7879938,-122.407437&frequency=680"

cURL (without geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?b and=AM&country=US&frequency=680&call_sign=KNBR"          |

Identify FM Radio Stations with call_sign

Target (with call_sign)

• FM radio station "KQED-FM in San Francisco, California, USA
• geolocation=37.7879938,-122.407437
• country=US
• frequency=88.5
• call_sign=KQED-FM cURL (with geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?b and=FM&geolocation=37.7879938,- 122.407437&frequency=88.5&call_sign=KQED-FM"

cURL (without geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?b and=FM&country=US&frequency=88.5&call_sign=KQED-FM"                          |

Identify FM Radio Stations with pi

Target (with pi)

• FM radio station "egoFM" in Munich, Germany
• geolocation=37.51,-122.0947
• frequency=97.7
• pi=1EA6
• signal=HD
• hd_multicast_value=1

cURL (with geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations? band=FM&geolocation=37.51,-122.0947&frequency=97.7& pi=1EA6&signal=HD&hd_multicast_value=1"

cURL (without geolocation)

Code
 
curl -X POST -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.2/radiostati ons/search? -H "Content-Type: application/json" -d {"frequency":"97.7", "pi":"28F7", "signal":"HD", "hdMulticastValue"\:1,"band":"FM"}

Identify DAB Radio Stations

Target

• DAB radio station "106.4 TOP FM" in Munich, Germany
• geolocation=48.1205,11.603337
• country=DE
• frequency=220.352
• eid=D073
• sid=D71D
• scids=0 cURL (with geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?b and=DAB&geolocation=48.1205,11.603337&frequency=220.352&ei d=D073&sid=D71D&scids=0"

cURL (without geolocation)

Code
 
curl -X GET -H "Authorization: Bearer gv4DVSpbh86XXnctAsec4DC45JMA" "https://api.rsid.music.gracenote.com/v1.1/radiostations?b and=DAB&country=DE&frequency=220.352&eid=D073&sid=D71D&sci ds=0"                    |