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:

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.

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