Podcast Catalog Reference

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 a catalog of all the podcasts that are available in your podcast skill so that Alexa can match users' voice requests with your content. This helps support utterances that include properties like podcast 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

Catalogs are JSON documents that describe the programs that your podcast skill supports.

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 naming conventions

Podcast catalog names must start with the prefix podcast_. The name can be up to 80 characters long. It can only contain alphanumeric characters (uppercase, lowercase and numbers), hyphens, and underscores. Amazon recommends using the following naming convention when uploading catalogs:

podcast_YYYYMMDD_N.json

YYYYMMDD is the podcast catalog upload date. N is the catalog version number.

Catalog types

The following table lists the supported catalog types for podcast skills and the corresponding type of content for each.

Catalog Type	Content
`AMAZON.ProgramSeries`	PROGRAM_SERIES

Catalog structure

A podcast catalog consists of a header, followed by an array of entities. The catalog contains one entity for each program series.

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 the catalog header for all podcast catalogs:

{
  "type": "AMAZON.ProgramSeries",
  "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. For more information about entity ID uniqueness and updating entities, see Frequently asked questions.

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.

Field	Required
`id`	Yes
`lastUpdatedTime`	Yes
`deleted`	Yes (must be `true`)
`locales`	No

Program series catalog (`AMAZON.ProgramSeries`)

Each entity in a program series catalog (AMAZON.ProgramSeries) includes the following fields:

Field	Description	Type	Required
`id`	Unique entity ID between 1 and 256 characters that is consistent and globally unique across all catalogs for this skill.	String	Yes
`names`	The canonical names for this entity	Array	Yes
`name.language`	The language of this name, for example "en"	enum	Yes
`name.value`	The text of the name, between 1 and 512 characters, in the associated language	String	Yes
`popularity`	Popularity of this entity within this catalog	object	Yes
`popularity.default`	Default popularity of this entity within this catalog, between 0 and 100	Integer	Yes
`popularity.overrides`	Popularity values for specific locales that override the default popularity	Array	No
`lastUpdatedTime`	ISO 8601 timestamp (UTC) for the time when this entity was last updated	String	Yes
`locales`	Locales where this entity is available	Array	No
`locale`	A locale that includes language and country	Object	No
`locale.country`	The country of this locale, for example, "US"	Enum	No
`locale.language`	The language of this locale, for example, "en"	Enum	No
`alternateNames`	Aliases and other names for this entity	Array	No
`alternateName.language`	The language of this alternate name	Enum	No
`alternateName.values`	Array of alternate names in the associated language	Array	No
`languageOfContent`	The primary languages present in this entity	Array	No
`language`	Canonical representation of a language. For details, see BCP-47.	Enum	No
`deleted`	True if this entity needs to be deleted from the ingested catalog	Boolean	No

Podcast program series catalog example

{
  "type": "AMAZON.ProgramSeries",
  "version": 2.0,
  "locales": [
    {
      "country": "US",
      "language": "en"
    }
  ],
  "entities": [
    {
      "id": "program.series.001",
      "names": [
        {
          "language": "en",
          "value": "[PROGRAM_SERIES_NAME]"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "[ALTERNATE_PROGRAM_SERIES_NAME]"
          ]
        }
      ],
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "languageOfContent": [
        "en"
      ],
      "deleted": false
    },
    {
      "id": "program.series.002",
      "names": [
        {
          "language": "en",
          "value": "[PROGRAM_SERIES_NAME]"
        }
      ],
      "popularity": {
        "default": 100,
        "overrides": [
          {
            "locale": {
              "country": "US",
              "language": "en"
            },
            "value": 100
          }
        ]
      },
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "alternateNames": [
        {
          "language": "en",
          "values": [
            "[ALTERNATE_PROGRAM_SERIES_NAME]"
          ]
        }
      ],
      "locales": [
        {
          "country": "US",
          "language": "en"
        }
      ],
      "languageOfContent": [
        "en"
      ],
      "deleted": false
    },
    {
      "id": "program.series.999",
      "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
      "deleted": true
    }
  ]
}

Frequently asked questions

Q: What happens after a catalog upload?

The catalog validation happens automatically after you upload the catalog. You receive an email notification stating the status of the catalog ingestion process, along with a detailed log file listing any warnings or errors to.

Q: Is there a file size limit for catalogs?

The maximum catalog file size is 5 TB.

Q: What is the current process for updating entities in a catalog?

The previous catalog uploaded isn't deleted, but instead the uploaded files are applied as updated to the catalog entities.

The last update time of entities are checked to make sure it's appropriate apply the new update.

This brings up two important points:

The entity ID must be unique across all entities within a single catalog and must not change from upload to upload.
1. You can remove or delete an entity by setting the deleted attribute to true and setting the lastUpdatedTime.
2. You can override an invalid entity by sending the new (correct) values for the same entity ID to your Alexa Podcast representative (same process as a regular update).
To change an entity ID, perform the following steps:
1. Delete the old entity by setting the deleted attribute to true and setting the lastUpdatedTime.
2. Upload the new entity (with a new entity ID) as a normal catalog update.

Q: Can I update or refresh an entire catalog?

Amazon doesn't recommend this unless the catalog update process has caused a serious problem, such as duplicate entity IDs and entries for the same entities. Otherwise, if the entities remain intact and correct, Amazon recommends sending incremental updates and using the deleted and lastUpdatedTime properties.

If you do need to have your entire catalog purged, Amazon doesn't currently have an automated process for doing an entire catalog refresh – that is, deleting the old catalog and ingesting a new one. This is a manual operation that you must coordinate with your Alexa Podcast representative.

Q: Do I need to process the entire catalog, or can I process partial entities?

Amazon expects any catalog that you upload to pass basic validation, such as being in proper JSON format.

If the entire catalog fails to validate due to invalid JSON format, the catalog is rejected as a whole, and no updates are applied to the Alexa Podcast catalog.

If only certain entities are invalid or incorrect – for example, if they are missing required properties or values aren't in the appropriate format – only those entities are rejected. The entities that passed validation are ingested as normal.