Podcast Catalog Reference

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:

  1. 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).
  2. 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.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment