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:
- The entity ID must be unique across all entities within a single catalog and must not change from upload to upload.
- You can remove or delete an entity by setting the
deleted
attribute to true and setting thelastUpdatedTime
. - 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).
- You can remove or delete an entity by setting the
- To change an entity ID, perform the following steps:
- Delete the old entity by setting the
deleted
attribute to true and setting thelastUpdatedTime
. - Upload the new entity (with a new entity ID) as a normal catalog update.
- Delete the old entity by setting the
- The entity ID must be unique across all entities within a single catalog and must not change from upload to upload.
- 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
andlastUpdatedTime
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.