Podcast Catalog Reference

Upload a catalog of all the podcasts that are available in your podcast skill to help Alexa match users' voice requests with your content.

Overview

Catalogs are JSON documents that describe the programs that you make available through your podcast skill.

The following sections describe the format to use for your podcast catalog and some best practices for creating and uploading catalogs.

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 supported catalog types for podcast skills and the corresponding type of content for each. Currently AMAZON.ProgramSeries is the only catalog type for podcasts.

Catalog Type Content
AMAZON.ProgramSeries PROGRAM_SERIES

Podcast catalog (AMAZON.ProgramSeries)

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

Catalog header

A catalog header includes the following fields:

  • type
  • version
  • locales

All of these fields are required.

For more details, 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, one for each program series in the catalog. Each entity has an identifier, specified in the id field. Each entity's id should be unique, and it should remain the same for the entity's entire lifecycle, as summarized in the following points:

  1. The entity ID must be unique across all entities within a single catalog and must not change from upload to upload. <div markdown="span" class="alert alert-info" role="alert"> Note: deleted entities don't count as duplicates.</div>
    1. You can remove or delete an entity by setting the deleted attribute to true and setting the lastUpdatedTime, or by creating a corresponding deleted entity. For details, see How to mark a program series as deleted.
    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.

How to mark a program series as deleted

The catalog schema defines a special entity called deleted. A deleted entity has the same id as an existing entity in the catalog. Its presence indicates that the existing entity should be deleted from the catalog. Thus you can delete an entity in either of two ways: by setting the deleted field of an existing entity to true, or by adding a new deleted entity with the same entity ID to the catalog. The deleted entity requires only enough information to identify the existing entity, as shown in the following table of deleted entity fields.

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

Why and how to use the availability field

You can use the availability field to add podcasts to your catalog even if they're not currently available. Two things happen when a skill adds a podcast that's not currently available in the skill's catalog. First, Alexa trains its voice models to recognize the podcast. Second, the podcast becomes eligible for matching to customer utterances during Alexa's entity resolution.

The availability field takes the following values:

  • AVAILABLE: The podcast is available. This is the default value.
  • NOT_AVAILABLE: The podcast isn't available.

Consider adding unavailable podcasts to your catalog in advance of an upcoming content release. By adding these podcasts to the catalog early, you allow time for Alexa's voice models to learn to recognize the content before your release.

Adding an unavailable podcast to a podcast catalog also improves your podcast skill's ability to accurately play back the podcasts that a customer requests and to return helpful errors when a customer requests content that's not available. For example, a request might be a good match to the unavailable podcast and a poor match to an available podcast. When the unavailable podcast isn't in the catalog, the skill only receives the poor match. When the unavailable podcast is in the catalog, the skill receives it in the ranked list of podcasts that match the utterance. The skill can then make an informed decision to play back the poor match (reducing customer friction, but risking disappointing playback), or to return an informative CONTENT_NOT_FOUND error.

When to mark a podcast entity as deleted versus unavailable

The deleted field takes precedence over the availability field. When you mark a podcast entity as deleted, the podcast isn't searchable. Alexa doesn't send a request for the podcast to the skill, and ignores the availability field. The best use of the deleted field to change a podcast entity ID or to remove nonsensical or duplicate entries that you added by accident.

Why and how to use the exclusivity and production fields

Use the exclusivity and production fields to improve request routing to your skill for podcasts that your podcast hosting service has a unique relationship with.

The exclusivity field tells Alexa that you have exclusive rights to distribute the full episode catalog for a particular podcast. Because certain episodes (or all of them) are exclusive to your service, your skill is likely to be better suited to handle customer requests for the podcast.

The exclusivity.degree field indicates whether some or all of the episodes are exclusive. COMPLETE means that all episodes are exclusive, and other providers shouldn't have this podcast at all. PARTIAL means that other providers may have some of the episodes for this podcast.

The exclusivity.criteria field allows for additional clarifications. This field is only meaningful if the value of exclusivity.degree is PARTIAL. The exclusivity.criteria field contains a list of exclusivityCriteria objects. Only one type of exclusivityCriteria object is currently supported: LATEST_EPISODE, which indicates that the latest episode of the podcast is exclusive to your service.

The production field tells Alexa about your service's involvement with the production of the content, for example, by identifying original content. This content might or might not be exclusive to your service. Only one production value is currently supported: ORIGINAL, which indicates that the content is original to your service.

Catalog field definitions

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

Field Description Type Required

id

Unique entity ID between one and 256 characters that's consistent and globally unique across all catalogs for this skill.

String

Yes

names

List of the canonical names for this entity.

Array

Yes

name.language

The language of this name, for example "en". For details, see BCP-47.

Enum

Yes

name.value

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

List of 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". For details, see BCP-47.

Enum

No

alternateNames

List of aliases and other names for this entity.

Array

No

alternateName.language

The language of the alternate names. For details, see BCP-47.

Enum

No

alternateName.values

List of alternate names in the associated language.

Array

No

languageOfContent

The primary languages present in this entity.

Array

No

authors

List of the creators of the show.

Array

No

author

An author.

Object

No

author.name

The name of the author, between 1 and 256 characters.

String

Yes

description

Description of the show.

Object

No

description.value

Show description, between 1 and 4000 characters. Generally is the RSS feed description.

String

Yes

description.language

The language of the description. For details, see BCP-47.

Enum

No

type

The itunes:type in the RSS feed: episodic (default) or serial.

Enum

No

categories

List of categories associated with this entity, in the same order listed in the RSS feed.

Array

No

category

Category and subcategories in the podcast RSS feed. You can nest categories by using the subcategories field.

Object

No

category.value

The text of the category, between 1 and 64 characters, in the associated language. Typically this is the itunes:category in the RSS feed. Must be valid based on the level of nesting in the category object.
Note: Use the & character rather than "&amp;".

String

Yes

category.subcategories

List of category objects, supporting subcategories as in RSS.

Array

No

feedUrl

RSS feed URL for the program series. Between 1 and 2048 characters. Use this field if your content hosting service uses a public RSS feed to automatically get new episodes from content creators.

String

No

providerRelationship

Description of any special relationships between your service and the entity.

Object

No

providerRelationship.availability

Indicates whether this show is available from your content hosting service: AVAILABLE or NOT_AVAILABLE.
For more details, see Why and how to use the availability field.

Enum

No

providerRelationship.production

Indicates your service's relationship with the production or ownership of the content. Only one production value is currently supported: ORIGINAL, which indicates that the content is original to your service. For details, see Why and how to use the exclusivity and production fields.

Enum

No

providerRelationship.exclusivity

Indicates whether your service has exclusive rights to the full episode catalog for this show — in other words, whether other services might have limited access to the episodes of this show, or no access at all. For details, see Why and how to use the exclusivity and production fields.

Object

No

providerRelationship.exclusivity.degree

The degree of episode exclusivity for this show: COMPLETE or PARTIAL.

Enum

Yes

providerRelationship.exclusivity.criteria

A list of exclusivity criteria describing which episodes are exclusive. This field is only meaningful if the value of providerRelationship.exclusivity.degree is PARTIAL.

Array

No

exclusivityCriteria

Object representing a criterion by which specific episodes are exclusive.

Object

No

exclusivityCriteria.type

Type of the exclusivity criteria. Currently the only possible value is LATEST_EPISODE.

Enum

Yes

deleted

Set this field to true, to mark the program series as deleted from the podcast catalog, or false otherwise.

Boolean

No

Podcast catalog example

{
    "type": "AMAZON.ProgramSeries",
    "version": 2,
    "locales": [{
        "country": "US",
        "language": "en"
    }],
    "entities": [{
        "id": "program.series.001",
        "names": [{
            "language": "en",
            "value": "PRIMARY NAME"
        }, {
            "language": "es",
            "value": "NOMBRE PRINCIPAL"
        }],
        "popularity": {
            "default": 100,
            "overrides": [{
                "locale": {
                    "country": "US",
                    "language": "en"
                },
                "value": 100
            }]
        },
        "lastUpdatedTime": "2018-08-01T00:00:00.000Z",
        "alternateNames": [{
            "language": "en",
            "values": ["alternate name", "variant name", "primary name with john doe"]
        }],
        "locales": [{
            "country": "US",
            "language": "en"
        }],
        "languageOfContent": ["en"],
        "feedUrl": "http://example-feed.org/feed",
        "providerRelationship": {
            "exclusivity": {
                "degree": "PARTIAL",
                "criteria": [{
                    "type": "LATEST_EPISODE"
                }]
            },
            "production": "ORIGINAL"
        },
        "authors": [{
            "name": "John Doe"
        }],
        "categories": [{
            "value": "Sports",
            "subcategories": [{
                "value": "Baseball"
            }, {
                "value": "Basketball"
            }]
        }, {
            "value": "News",
            "subcategories": [{
                "value": "Sports News"
            }]
        }],
        "type": "EPISODIC",
        "description": {
            "language": "en",
            "value": "Example Host1 and Host2 talk about all things ..."
        },
        "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"],
        "categories": [{
            "value": "Arts"
        }],
        "feedUrl": "http://example-feed.org/feed",
        "providerRelationship": {
            "availability": "NOT_AVAILABLE"
        },
        "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.
Q: Is there a file size limit for catalogs?
The maximum catalog file size is 5 TB.
Q: What's the current process for updating entities in a catalog?
Amazon applies the contents of the new uploaded catalog as an update to the catalog entities, and doesn't delete existing entities in the catalog.

Amazon checks the lastUpdatedTime field of the catalog entities to determine whether to apply the new 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 need to remove or replace your entire catalog, contact 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 correct JSON format.

If the entire catalog fails to validate due to invalid JSON format, Amazon rejects the catalog as a whole and doesn't update your podcast catalog.

If only certain entities are invalid or incorrect – for example, if they're missing required properties or values aren't in the appropriate format – Amazon rejects only those entities and ingests the entities that passed validation.