Music Catalog Reference

Note: Sign in to the developer console to build or publish your skill.

Important: Anyone can build a music skill for public distribution in the United States. However, radio and podcast skills are currently in developer preview. To register your radio or podcast skill for the preview, contact your Alexa Music, Radio, or Podcast representative.

You should upload catalogs of items that are available in your music skill to Alexa so that Alexa can match users voice requests with your content. This helps support utterances like:

Alexa, play Better Man by Pearl Jam – Alexa searches for the song "Better Man" by the artist "Pearl Jam" in the music skill catalogs.
Alexa, play sleepy time radio – Alexa searches for the station "sleepy time" in the music skill catalogs.

The following sections describe the supported catalog types, the format to use for your catalogs, and some best practices for catalogs.

Overview

Catalogs are JSON documents that describe the content (songs, artists, stations, etc.) that your music skill supports. There are six types of catalogs, which correspond to the different types of content.

The maximum number of entities in a catalog is 500,000. This limit is cumulative, so if you upload 250,000 entities to a catalog one day, then upload an additional 250,000 entities to the same catalog the next day, you have reached the limit for that catalog. If you require support for catalogs with more than 500,000 entities, contact Amazon to request an increase to this limit.

Catalog types

The following table lists the six types of catalogs and the corresponding type of content.

Catalog Type	Content
`AMAZON.BroadcastChannel`	Station
`AMAZON.Genre`	Genre
`AMAZON.MusicAlbum`	Album
`AMAZON.MusicGroup`	Artist
`AMAZON.MusicPlaylist`	Playlist
`AMAZON.MusicRecording`	Track

For examples of each type of catalog, see the following sections.

Catalog structure

A catalog starts with a header. The header structure is the same for all catalog types.

Catalog header

A catalog header includes the following fields:

type
version
locales

All of these fields are required.

For more information about these fields, see the catalog field definitions.

The following example shows a catalog header:

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

Catalog entities

The catalog header is followed by an array of entities. The entities are different for each catalog type. For more information, see the section for each catalog type:

Station
Genre
Album
Artist
Playlist
Track

Entity IDs

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

Catalog can also 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

All of the following example catalogs have a deleted entity.

Station catalog (`AMAZON.BroadcastChannel`)

Each entity in a station catalog (AMAZON.BroadcastChannel) includes the following fields:

Field	Required
`id`	Yes
`names`	Yes
`popularity`	Yes
`popularity.default`	Yes
`popularity.overrides`	No
`lastUpdatedTime`	Yes
`locales`	No
`alternateNames`	No
`channelId`	No
`callSign`	No
`frequency`	No
`ownedAndOperated`	No
`languageOfContent`	No
`deleted`	No

For more information about these fields, see the catalog field definitions.

Station catalog example

{
  "type": "AMAZON.BroadcastChannel",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "station.001",
      "names": [
        {
          "language": "en",
          "value": "Today's Pop Hits"
        }
      ],
      "type": "Live",
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Popular Music",
            "Pop Music",
            "Pop Hits"
          ]
        }
      ],
      "channelId": 101,
      "callSign": "KEXP",
      "frequency": "90.3",
      "ownedAndOperated": "No",
      "languageOfContent": [
        "en"
      ],
      "deleted": false
    },
    {
      "id": "station.002",
      "names": [
        {
          "language": "en",
          "value": "Classical Music"
        }
      ],
      "type": "Recorded",
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Popular Music",
            "Pop Music",
            "Pop Hits"
          ]
        }
      ],
      "channelId": 102,
      "ownedAndOperated": "No",
      "languageOfContent": [
        "en"
      ],
      "deleted": false
    },
    {
      "id": "station.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Genre catalog (`AMAZON.Genre`)

Each entity in a genre catalog (AMAZON.Genre) includes the following fields:

Field	Required
`id`	Yes
`names`	Yes
`popularity`	Yes
`popularity.default`	Yes
`popularity.overrides`	No
`lastUpdatedTime`	Yes
`locales`	No
`alternateNames`	No
`deleted`	No

For more information about these fields, see the catalog field definitions.

Genre catalog example

{
  "type": "AMAZON.Genre",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "genre.001",
      "names": [
        {
          "language": "en",
          "value": "Rock"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Rock and roll",
            "Rock 'n' roll",
            "Classic rock"
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "genre.002",
      "names": [
        {
          "language": "en",
          "value": "Atmospheric Electronic"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Ambient"
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "genre.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Album catalog (`AMAZON.MusicAlbum`)

Each entity in an album catalog (AMAZON.MusicAlbum) includes the following fields:

Field	Required
`id`	Yes
`names`	Yes
`popularity`	Yes
`popularity.default`	Yes
`popularity.overrides`	No
`lastUpdatedTime`	Yes
`alternateNames`	No
`languageOfContent`	No
`releaseType`	No
`artists`	No
`deleted`	No

For more information about these fields, see the catalog field definitions.

Album catalog example

{
  "type": "AMAZON.MusicAlbum",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "album.001",
      "names": [
        {
          "language": "en",
          "value": "Nevermind"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "never mind"
          ]
        }
      ],
      "languageOfContent": [
        "en"
      ],
      "releaseType": "Studio Album",
      "artists": [
        {
          "id": "artist.001",
          "names": [
            {
              "language": "en",
              "value": "Nirvana"
            }
          ],
          "alternateNames": [
            {
              "language": "en",
              "values": [
                "Kurt Cobain"
              ]
            }
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "album.002",
      "names": [
        {
          "language": "en",
          "value": "Louder Than Love"
        }
      ],
      "popularity": {
        "default": 50,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 75
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": []
        }
      ],
      "languageOfContent": [
        "en"
      ],
      "releaseType": "Studio Album",
      "artists": [
        {
          "id": "artist.002",
          "names": [
            {
              "language": "en",
              "value": "Soundgarden"
            }
          ],
          "alternateNames": [
            {
              "language": "en",
              "values": [
                "sound garden"
              ]
            }
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "album.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Artist catalog (`AMAZON.MusicGroup`)

Each entity in an artist catalog (AMAZON.MusicGroup) includes the following fields:

Field	Required
`id`	Yes
`names`	Yes
`popularity`	Yes
`popularity.default`	Yes
`popularity.overrides`	No
`lastUpdatedTime`	Yes
`locales`	No
`alternateNames`	No
`deleted`	No

For more information about these fields, see the catalog field definitions.

Artist catalog example

{
  "type": "AMAZON.MusicGroup",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "artist.001",
      "names": [
        {
          "language": "en",
          "value": "Macklemore"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Ben Haggerty",
            "Benjamin Hammond Haggerty"
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "artist.002",
      "names": [
        {
          "language": "en",
          "value": "Modest Mouse"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": []
        }
      ],
      "deleted": false
    },
    {
      "id": "artist.003",
      "names": [
        {
          "language": "en",
          "value": "Alice in Chains"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "deleted": false
    },
    {
      "id": "artist.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Playlist catalog (`AMAZON.MusicPlaylist`)

Each entity in a playlist catalog (AMAZON.MusicPlaylist) includes the following fields:

Field	Required
`id`	Yes
`names`	Yes
`popularity`	Yes
`popularity.default`	Yes
`popularity.overrides`	No
`lastUpdatedTime`	Yes
`locales`	No
`alternateNames`	No
`deleted`	No

For more information about these fields, see the catalog field definitions.

Playlist catalog example

{
  "type": "AMAZON.MusicPlaylist",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "playlist.001",
      "names": [
        {
          "language": "en",
          "value": "Friday Night Party Mix"
        }
      ],
      "popularity": {
        "default": 90,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 90
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Friday Night Party",
            "Party Music"
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "playlist.002",
      "names": [
        {
          "language": "en",
          "value": "Classical Focus"
        }
      ],
      "popularity": {
        "default": 60,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 60
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "Classical Study"
          ]
        }
      ],
      "deleted": false
    },
    {
      "id": "playlist.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Track catalog (`AMAZON.MusicRecording`)

Each entity in a track catalog (AMAZON.MusicRecording) includes the following fields:

Field	Required
`id`	Yes
`names`	Yes
`popularity`	Yes
`popularity.default`	Yes
`popularity.overrides`	No
`lastUpdatedTime`	Yes
`locales`	No
`alternateNames`	No
`languageOfContent`	No
`releaseType`	No
`artists`	No
`albums`	No
`deleted`	No

For more information about these fields, see the catalog field definitions.

Track catalog example

{
  "type": "AMAZON.MusicRecording",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "track.001",
      "names": [
        {
          "language": "en",
          "value": "Heart-Shaped Box"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "heart shaped box"
          ]
        }
      ],
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "languageOfContent": [
        "en"
      ],
      "artists": [
        {
          "id": "artist.001",
          "names": [
            {
              "language": "en",
              "value": "Nirvana"
            }
          ],
          "alternateNames": [
            {
              "language": "en",
              "values": [
                "Kurt Cobain"
              ]
            }
          ]
        }
      ],
      "albums": [
        {
          "id": "album.001",
          "names": [
            {
              "language": "en",
              "value": "In Utero"
            }
          ],
          "alternateNames": [
            {
              "language": "en",
              "values": []
            }
          ],
          "releaseType": "Studio Album"
        }
      ],
      "deleted": false
    },
    {
      "id": "track.002",
      "names": [
        {
          "language": "en",
          "value": "Black Hole Sun"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "black whole sun",
            "black whole son",
            "black hole son"
          ]
        }
      ],
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "languageOfContent": [
        "en"
      ],
      "artists": [
        {
          "id": "artist.002",
          "names": [
            {
              "language": "en",
              "value": "Soundgarden"
            }
          ],
          "alternateNames": [
            {
              "language": "en",
              "values": [
                "sound garden"
              ]
            }
          ]
        }
      ],
      "albums": [
        {
          "id": "album.002",
          "names": [
            {
              "language": "en",
              "value": "Superunknown"
            }
          ],
          "alternateNames": [
            {
              "language": "en",
              "values": [
                "super unknown"
              ]
            }
          ],
          "releaseType": "Studio Album"
        }
      ],
      "deleted": false
    },
    {
      "id": "track.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Catalog field definitions

The following table lists the fields that you can use in catalogs, and a description of each.

Field	Description	Type	Values
`albums`	Albums associated with this entity	array	[{id, names, alternateNames, releaseType}]
`alternateNames`	Aliases and other names for this entity	array	[{language, values}]
`alternateName.language`	The language of this alternate name	enum	language
`alternateName.values`	Array of alternate names in the associated language	array	[string]
`artists`	Artists associated with this entity	array	[{id, names, alternateNames}]
`callSign`	The call sign of the station, for example "KEXP" or "WNYC"	string	between 1 and 64 characters
`channelId`	The unique address by which the station can be identified in a provider lineup. In the US, this is typically a number.	integer	Must be greater than or equal to zero.
`country`	Canonical representation of a country	enum	ISO-3166 alpha-2
`deleted`	True if this entity needs to be deleted from the ingested catalog	boolean
`frequency`	The radio frequency of the station, for example 90.3 or 93.9	string	between 1 and 64 characters
`id`	Unique entity ID that is consistent and globally unique across all catalogs for this skill. For example, if an album has an artist, the ID of that artist should reference the same entity in the artist catalog	string	between 1 and 256 characters
`languageOfContent`	The primary languages present in this entity	array	[language]
`language`	Canonical representation of a language	enum	BCP-47
`lastUpdatedTime`	Timestamp (UTC) for when this entity was last updated	string	ISO 8601 in UTC
`locales`	Locales where this entity is available	array	[{locale}]
`locale`	A locale that includes language and country	object	{country, language}
`locale.country`	The country of this locale	enum	country
`locale.language`	The language of this locale	enum	language
`names`	The canonical names for this entity	array	[{language, value}]
`name.language`	The language of this name	enum	language
`name.value`	The text of the name in the associated language	string	between 1 and 512 characters
`ownedAndOperated`	Freeform text to indicate whether the music service provider owns and operates this station; for example, "No", "Yes", "Exclusive"	string	between 1 and 64 characters
`popularity`	Popularity of this entity within this catalog	object	{default, overrides}
`popularity.default`	Default popularity of this entity within this catalog	integer	between 0 and 100
`popularity.overrides`	Popularity values for specific locales that override the default popularity	array	[{locale, value}]
`releaseType`	The type of album that was released; for example, Studio Album, Soundtrack Album, Live Album	string	between 1 and 64 characters
`type`	Type of entity in this catalog	enum	["AMAZON.MusicGroup", "AMAZON.MusicRecording", "AMAZON.MusicAlbum", "AMAZON.MusicPlaylist", "AMAZON.Genre", "AMAZON.BroadcastChannel"]
`version`	Amazon catalog schema version, currently 2.0	float	multiples of 0.1

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023

Music Catalog Reference

Overview

Catalog types

Catalog structure

Catalog header

Catalog entities

Entity IDs

Deleted entities

Station catalog (AMAZON.BroadcastChannel)

Station catalog example

Genre catalog (AMAZON.Genre)

Genre catalog example

Album catalog (AMAZON.MusicAlbum)

Album catalog example

Artist catalog (AMAZON.MusicGroup)

Artist catalog example

Playlist catalog (AMAZON.MusicPlaylist)

Playlist catalog example

Track catalog (AMAZON.MusicRecording)

Track catalog example

Catalog field definitions

Was this page helpful?

Station catalog (`AMAZON.BroadcastChannel`)

Genre catalog (`AMAZON.Genre`)

Album catalog (`AMAZON.MusicAlbum`)

Artist catalog (`AMAZON.MusicGroup`)

Playlist catalog (`AMAZON.MusicPlaylist`)

Track catalog (`AMAZON.MusicRecording`)