Radio Catalog Reference
You should upload a catalog of all your stations that are available in your radio skill so that Alexa can match users voice requests with your content. This helps support utterances that include properties like station name, alternate station name, frequency, genre, and call sign.
The following sections describe the supported catalog types, the format to use for your catalogs, and some best practices for catalogs.
Overview
A radio catalog is a JSON document that describe the content (station name, call sign, frequency, etc.) that your skill supports. The maximum number of entities in a catalog is 500,000. If you require support for catalogs with more than 500,000 entities, contact us to request an increase to this limit.
Catalog structure
A catalog encompasses a header, entity ID, and entities. An example and field requirements are specified below.
Catalog header
A catalog header includes the following fields, which are all required:
type
version
locales
The following example shows a catalog header:
{
"type": "AMAZON.MusicGroup",
"version": 2.0,
"locales": [
{
"country": "US",
"language": "en"
}
]
}
Catalog entities and entity IDs
The catalog header is followed by an array of entities
. Each entity in a catalog has an identifier, specified in the id
field. Each entity's id
should be unique, and for a given entity, the id
should remain the same for the entity's entire lifecycle.
Deleted entities
The catalog include a special entity called deleted
. A deleted
entity indicates that the referenced entity should be deleted. You can choose to set the deleted
field of an existing entity to true
, or add a new deleted
entity with the corresponding entity ID in the catalog. The benefit of using a deleted
entity is that deleted
entities have only three required fields regardless of catalog type:
Field | Required |
---|---|
id |
Yes |
lastUpdatedTime |
Yes |
deleted |
Yes (must be true ) |
locales |
No |
Station catalog example
Adding to the catalog header, the following is an example showing the array of entities.
{
"type": "AMAZON.TerrestrialRadioChannel",
"version": 2.0,
"locales": [
{
"country": "US",
"language": "en"
}
],
"entities": [
{
"id": "station.001",
"names": [
{
"language": "en",
"value": "Today's Pop Hits Seattle"
}
],
"lastUpdatedTime": "2018-08-01T00:00:00.000Z",
"locales": [
{
"country": "US",
"language": "en"
}
],
"alternateNames": [
{
"language": "en",
"values": [
"Today's Pop Hits",
"Pop Hits 90.3"
]
}
],
"location": {
"city": "Seattle",
"subdivision": "US-WA",
"country": "US",
"geoCoordinates": {
"latitude": 41.98032,
"longitude": -3.81729
},
},
"callSign": "KEXP",
"frequency": "90.3",
"band": "AM",
"genres": [
{
"language": "en",
"value": "top hits"
}
],
"ownedAndOperated": "OWNED_AND_OPERATED",
"languageOfContent": [
"en"
],
"deleted": false
}
]
}
Catalog fields
The following table lists the fields and further information about each field.
Field | Mandatory/optional | Type | Notes |
---|---|---|---|
type | Mandatory | enum | Always Amazon.TerrestrialRadioChannel for radio content. |
version | Mandatory | float | Multiples of 0.1. Catalog version is currently 2.0. |
locales | Mandatory | array | Superset of all entity types included in the catalog. |
locale.country | Mandatory | enum | ISO-3166-1 alpha-2 value. |
locale.language | Mandatory | langstring | |
entities | Mandatory | array | List object containing radio stations. |
id | Mandatory | string | Between 1 and 256 characters. This is the entity ID set by the provider that Alexa will use to look up radio content in the provider's catalog. |
names | Mandatory | array | Must include at least one name. |
name.language | Mandatory | langstring | |
name.value | Mandatory | string | Between 1 and 512 characters. |
locales | Optional | array | Only required if overriding locale specified in header. |
locale.country | Mandatory (if parent present) | enum | ISO-3166 alpha-2 value. |
locale.language | Mandatory (if parent present) | langstring | |
alternateNames | Optional | array | |
alternateName.language | Mandatory (if parent present) | langstring | |
alternateName.value | Mandatory (if parent present) | array | Between 1 and 512 characters. |
location | Mandatory | object | |
location.city | Mandatory | string | Free text, between 1 and 64 characters. |
location.subdivision | Optional | enum | ISO_3166-2 country code. |
location.country | Optional | enum | ISO_3166-1 alpha 2 value. |
geoCoordinates | Mandatory | object | Latitude and longitude are both mandatory in order to provide location-based station search. |
geoCoordinates.latitude | Mandatory | float | Between -90 and 90. |
geoCoordinates.longitude | Mandatory | float | Between -180 and 180. |
callSign | Optional | string | Free text, between 1 and 64 characters. |
frequency | Mandatory | string | Free text, between 1 and 8 characters. |
genres | Optional | array | |
genre.language | Mandatory | langstring | Language of genre. |
genre.value | Mandatory | string | Free text, between 1 and 64 characters. |
ownedAndOperated | Mandatory | enum | Confirm ownership of station by specifying OWNED_AND_OPERATED. |
languageOfContent | Mandatory | array | Array of langstring. |
band | Optional | enum | Choice of AM, FM, HD1, HD2, HD3, DAB, DAB+. Between 1 and 64 characters. |
slogan | Optional | string | Between 1 and 512 characters. |
deleted | Mandatory | boolean | Defaults to false. |
lastUpdatedTime | Mandatory | string | ISO 8601 timestamp (UTC) for when this entity was last updated. |
Pre-modeled English Radio Genres
You can use the following English radio genre values that Alexa already understands:
- sixties
- seventies
- eighties
- nineties
- two thousands
- adult contemporary
- adult rock
- alternative
- blues
- christian
- gospel
- classic rock
- classical
- college rock
- comedy
- country
- dance
- edm
- hip hop
- holiday
- international
- jazz
- kids
- latin
- metal
- variety, mixed
- news
- conservative talk
- oldies
- pop
- punk
- r and b
- reggae
- rock
- romantic ballad
- smooth jazz
- soft rock
- spanish
- sports
- top forty
- weather
- world
Last updated: Dec 29, 2020