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.

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.

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:

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.

Last updated: Dec 06, 2023