Radio Catalog Reference

When you upload a catalog of the stations available in your radio skill, Alexa can match users' voice requests with your content. The catalog helps support utterances that include properties like frequency, genre, and callSign.

The following sections describe the radio catalog structure and supported catalog fields.

Catalog structure

A radio catalog is a JSON document that describes the content your skill supports. The maximum number of entities in the catalog is 500,000. If you require support for a larger catalog, contact your Alexa Music, Radio, or Podcast representative.

A catalog consists of a header and an array of entities. The following sections specify field requirements for those components.

As shown in the following example, a catalog header has three required fields.

  • type
  • version
  • locales
{
  "type": "AMAZON.MusicGroup",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ]
}

Entities and entity IDs

The catalog header is followed by an array of entities. Each catalog entity has a unique identifier. This identifier is specified in the id field. The id must remain the same throughout the entity's lifecycle.

Deleted entities

The deleted field indicates that the referenced entity must be deleted. You can either set an existing deleted field to true or add a new deleted field to the applicable entity ID. The following table shows the fields required or allowed in a deleted entity, regardless of catalog type.

Field Required

id

Yes

lastUpdatedTime

Yes

deleted

Yes (must be true)

locales

No

Station catalog example

The following example shows an array of entities after the header.

{
    "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 shows the available catalog fields.

Field Required Type Notes

type

Yes

enum

For radio content, always use Amazon.TerrestrialRadioChannel

version

Yes

float

Multiples of 0.1. Catalog version is currently 2.0

locales

Yes

array

Superset of all entity types in the catalog

locale.country

Yes

enum

ISO-3166-1 alpha-2 value

locale.language

Yes

langstring

Language that corresponds to the specified locale

entities

Yes

array

List of radio stations

id

Yes

string

Entity ID (between 1 and 256 characters) set by the provider and used by Alexa to look up radio content in the provider's catalog

names

Yes

array

Must include one or more

name.language

Yes

langstring

Language field

name.value

Yes

string

Between 1 and 512 characters

locales

No

array

Only required if primary locale is specified in header

locale.country

Yes (if parent present)

enum

ISO-3166 alpha-2 value

locale.language

Yes (if parent present)

langstring

Language field

alternateNames

No

array

Alternative names

alternateName.language

Yes (if parent present)

array

Language for alternative names

alternateName.value

Yes (if parent present)

array

Between 1 and 512 characters

location

Yes

object

Locale field

location.city

Yes

string

Free text, between 1 and 64 characters

location.country

No

enum

ISO_3166-1 alpha 2 value

geoCoordinates

Yes

object

Latitude and longitude are both required for location-based station search

geoCoordinates.latitude

Yes

float

Between -90 and 90

geoCoordinates.longitude

Yes

float

Between -180 and 180

callSign

No

string

Free text, between 1 and 64 characters

frequency

Yes

string

Free text, between 1 and 8 characters

genres

No

array

Musical genres

genre.language

Yes

langstring

Language of genre

genre.value

Yes

string

Free text, between 1 and 64 characters

ownedAndOperated

Yes

enum

To confirm station ownership, specify OWNED_AND_OPERATED, or use AGGREGATOR as the value. See note that follows table.

languageOfContent

Yes

array

Array of langstrings

band

No

enum

Choice of AM, FM, HD1, HD2, HD3, DAB, DAB+ (between 1 and 64 characters)

slogan

No

string

Between 1 and 512 characters

deleted

Yes

boolean

Defaults to false

lastUpdatedTime

Yes

string

ISO 8601 timestamp (UTC) that shows when this entity was last updated

Radio genres

Use radio genres from the following pre-modeled English-language values.

  • 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
Was this page helpful?

Last updated: Nov 27, 2023

DevAssistant
Amazon Developer Assistant