Catalog Reference

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 your artist catalog one day, then upload an additional 250,000 entities to your artist catalog the next day, you have reached the limit for your artist catalog. If you require support for catalogs with more than 500,000 entities, contact us 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:

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, e.g. "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, e.g. 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