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