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.

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:

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

Note: If you use the availability field, you should still return error codes like CONTENT_NOT_FOUND or GEOGRAPHICAL_RESTRICTION_ERROR as needed in your skill's GetPlayableContent response.

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 `"&"`.	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.