Your Alexa Consoles
Sign In
Sign In

Echo Show Video Skill API Reference

The Echo Show Video Skill API Reference details how to use a set of directives in AWS Lambda to accomplish several Echo Show capabilities.

Search using criteria like VideoName, ActorName, GenreName, etc., by querying the content providers for content to display. Potential utterances include:

  • "Search for movies with Tom Hanks." (ActorName)
  • "Find 'The Big Bang Theory.'" (TV Show)
  • "Find 'The Big Bang Theory' Season 1 episode 4."" (VideoName, Season, and Episode)
  • "Search for Interstellar." (Movie)
  • "Search for comedy movies." (Genre)
  • "Search comedy movies with Tom Hanks." (Actor and Genre)

Browse

Browse user's watch list, video library, recordings, etc., on the device. Potential utterances include:

  • "Show me my video library."
  • "Show me my watch list."
  • "Show me my recordings."

Pagination

Users may go to the "next page" of search results, or scroll beyond the viewable search results on the screen.

Quick Play

Search for movies, TV shows, recording, etc., using criteria such as VideoName, ActorName, or GenreName by querying content providers for the content to play on the device. Then, go directly into playback of that content (instead of showing search results, etc.). Potential utterances include:

  • "Play a movie with Tom Hanks."
  • "Play Interstellar." 
  • "Play a comedy movie."
  • "Play 'The Big Bang Theory.'"
  • "Play 'The Big Bang Theory' Season 1, episode 6."
  • "Play a movie." 

Channel Navigation

Play a live stream or recording of a channel for the user. Potential utterances include:

  • "Tune to CNN."
  • "Tune to ESPN."

Play from Search Results

Play a video from the search results shown on the device. The user can play using voice or simply by tapping on an item on the screen. Potential utterances include:

  • "Play number 1."
  • "Play the second one."
  • "Select number 1."
  • "Select the second one."

Recommendations

Search for recommendations by explicitly asking for something like "Show me recommended movies," or just by saying "Open Amazon Video," which translates to searching for recommendations.  

Landing Page

Alexa renders a "landing page" for your content when users say a phrase such as "Open your app name." It is analogous to an app home screen.

Alexa directives in the Lambda

You can apply the previously mentioned capabilities through the following Alexa directives in the Lambda:

GetDisplayableItems
This API is called when the user requests to search videos and view results on the device. You can search content based on the criteria in the request and return entity IDs for the videos corresponding to the search request. If there is no content found for the request, then an appropriate error response should be returned.
GetDisplayableItemsMetadata
This API is called to obtain additional metadata for results you previously returned via GetDisplayableItems for a set of entity IDs. The metadata contains information required by Alexa to display the entity IDs as search results on the device. 
GetPlayableItems
This API is called when the user requests to play a video on the device. You can search content based on the criteria in the request and return entity ID for the video corresponding to the request. Result returned from this API should favor videos that the user is entitled to play through their subscription (if applicable). If there are no videos for that request, then an appropriate Error Response code should be returned. 
GetPlayableItemsMetadata
This API is called to obtain additional metadata for results you previously returned through GetPlayableItems for a set of entity IDs. The metadata contains information required for playing the video as well as to render an appropriate prompt to the user. 
GetBrowseNodeItems
Search results on Echo Show can be merged into browse nodes with multiple layers. Users can choose to drill down on those grouped result items by clicking on them to see more results under that grouping. This API should return items that are part of the specified group in the directive.
GetNextPage
This API is called when the user tries to view more results on the screen by scrolling than are currently displayed on the screen. This API is called to dynamically fetch more results to show on the screen, once the metadata for those results has been fetched. 

SEARCH

GetDisplayableItems

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetDisplayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Video",
                    "value": "Manchester by the Sea",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "en-US",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }           
        }
    }
}
Field Description Required Type Values
endpoint An endpoint object identifies the target for a directive and the origin of an event. For more information, see Endpoint object in the Smart Home Skill API Message Reference. Yes Object  
entities

A list of entity objects to search. 

The relationship between different entity types should usually be interpreted as an AND operation. For example, if the request contains `{genreName = "Comedy," actorName ="Tom Hanks"}`, it implies that the search result should contain Comedy movies/TV shows with Tom Hanks. 

However, if the request contains multiple entities of the same type, such as `{videoName = "Interstellar," VideoName = "Interstellar Wars"}`, then you can consider this as an OR operation and can search for all the entities in the request. If in doubt, you should assume that the top entity within the type (videoName in this case) is the most relevant.

Let’s say you have another request with `{mediaType = "MOVIE', genreName = "Comedy," actorName ="Tom Hanks," actorName = "Tom Hanks}`. This is assuming that there are multiple actors named Tom Hanks. In such cases, you can search for movies with all the actors in the request and then filter based on the Comedy genre to return all the search results.

Alexa does not rank the entities today because Alexa does not have a way to know what the user wants to play when there are multiple matching entities. 

 Yes List  
  type

Entity types for video content. For information about video content entity types, see Entity Types for Video Content in the Video Skill API Reference. In addition to that list, ASK has added the following types for Echo Show: LISTTYPE , SORTTYPE

LISTTYPE is populated when the user wants to browse his/her Watchlist or Library. For example, utterances like "Show me my Watchlist" or "Show me my Video Library." It can have the following enum values. 

- WATCHLIST: For "Show me my Watchlist" - Used to show videos the user has added to their watchlist.

- LIBRARY: For "Show me my Video Library" - Ised to show videos that are in the users' library. Typically, these are the videos that have been purchased by the user. 

SORTTYPE - This is used to give additional information about the request that should be used during the searches and how results need to be sorted. For example, for "Show me recommended movies" Alexa needs recommendations from the content provider. It can have the following enum values:

- RECOMMENDED - This value is populated for utterances like "Show me recommended movies," or "show me recommended action movies," etc.

 Yes String

MEDIATYPE, VIDEO, ACTOR, GENRE, FRANCHISE, SEASON, EPISODE

New entity type:

LISTTYPE 

 - WATCHLIST, LIBRARY

SORTTYPE

 - RECOMMENDED
  value The name of the entity. Yes String Example: Interstellar
 externalIds External identifiers for the entity, key is the provider, value is the ID.  No Map

key = "gracenote" or "gti" 

Id is the string identifier.
minResultLimit

The minimum number of results to return in this call for which a pageToken is accepted. 

If you return less than the `minResultLimit` field along with a `pageToken` to fetch more results, then Alexa does not consider the `pageToken` to fetch the new items and only displays whatever Alexa received.

For a `pageToken` to be considered for fetching more results, the number of items have to match at least the value in `minResultLimit`, however, the number of items can be more than `minResultLimit` up to a max of `maxResultLimit`. If the number of items is more than the `maxResultLimit`, then Alexa discards the items after the `maxResultLimit`.

 Yes Integer Example: 8
maxResultLimit A limit to the maximum number of results to return in this call. See description of `minResultLimit` field for more details. Yes Integer Example: 25
timeWindow

Provides the start and end times that the request should act on. This is usually used for Live TV or Recording only and not for On Demand content. Generally, if the time window is available and can be used to filter the results, the content provider should use it.

For providers that only search for On Demand content, the time window field is usually set to null and can be ignored.

For Live TV or Recording, if the user specifies the time window, for example, "Search for TV shows between 4 and 5 pm," or "Find TV shows recorded last week," then you should filter the results based on the start and end times whenever available.

Depending on the capabilities, either both the fields—"start" and "end"—can be present, or any one field can be present. For example for "Search TV shows between 4 and 5 pm," both the fields are present. For "Show me TV shows starting at 5 pm," only "start" field is populated while "end" is null.

   Object  
  start The start time of the time window. String containing a time in ISO 8601 format. No String Example: 2016-09-07T23:59:00+00:00
  end The end time of the time window. String containing a time in ISO 8601 format. No String Example: 2016-09-07T23:59:00+00:00
  contentType ContentType specifies the content category to be searched. Note that this is different from mediaType in the entitles. MediaType specifies the type of media to search for, example: Movies, or TV shows, etc. Therefore, if the user is interested in browsing recorded movies, he/she says something like "Show me recorded movies." In this case, the mediaType is set to "MOVIE," while contentType is set to "RECORDING." Similarly, when the user wants to Browse live tv content, he/she says something like "Show me what’s on now," and in this case, the contentType is set to "LIVE."  No Enum

RECORDING

LIVE

 
locale

The locale for the user that should be used to get displayable information for the search results. This is the locale that the user has asked for based on the language setting on the device. A locale in the same format specified for languages in the Network Working Group Best Current Practice 47 (BCP-47). For more information, see the BCP-47 document.

If an unrecognized locale is received, you should default to en-US.

 Yes String en-US, en-GB, de-DE

Response:

The response in this case is a list of entity IDs of the items to display on the device.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetDisplayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}
Field Description Required Type Values
nextToken Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests. No String opaque string
mediaItems A list of mediaIdentifiers for the videos that is shown as search results on the screen. Yes List  
mediaIdentifier Identifier for the mediaItem. Yes Object  
id An identifier for the video item that is used to fetch any display or playback related metadata information on subsequent calls to GetDisplayableItemsMetadata or GetPlayableItemsMetadata. This identifier is opaque to Alexa and is used as-is when querying for metadata information. Yes String opaque string

GetDisplayableItemsMetadata

Request: 

The request only contains a list of entity IDs that Alexa needs metadata for. The entity IDs are returned by the provider from a previous GetDisplayableItemsResults call that happened for the request.

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetDisplayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {        
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifiers": [
                {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                },
                {
                    "id": "channelId://provider1.channel.rp.1234-2345-63435-asdf"
                }
            ]
        }
    }
}

Response:

The response contains the metadata information required to populate the templates on our side and render the search results on the screen. The response only contains display related information in this case and no playback information is required in this case. 

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetDisplayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "The Big Bang Theory",
                    "contentType": "ON_DEMAND",
                    "releaseYear": "2014",
                    "selectionAction": "BROWSE",
                    "thumbnailImage": {
                        "contentDescription": "The Big Bang Theory Image",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "2h 49m"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Purchase Options",
                    "reviews": [
                        {
                            "totalReviewCount": 41951,
                            "type": "FIVE_STAR",
                            "ratingDisplayString": "4.06"
                        }
                    ],
                    "rating": {
                        "category": "PG-13"
                    }
                },
                {
                    "name": "The Big Bang Theory",
                    "contentType": "LIVE",
                    "releaseYear": "2011",
                    "selectionAction": "PLAY",
                    "thumbnailImage": {
                        "contentDescription": "The Big Bang Theory Image ",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "30 min"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Play Now",
                    "rating": {
                        "category": "TV-PG"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "number": "1234",
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9",
                                "uri": "someUrl"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name",
                                "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

Example payload for an ON_DEMAND movie

{
    "payload": {
        "searchResults": [
            {
                "name": "Interstellar",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "Interstellar Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h 49m"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "Purchase Options",
                "reviews": [
                    {
                        "totalReviewCount": 41951,
                        "type": "FIVE_STAR",
                        "ratingDisplayString": "4.06"
                    }
                ],
                "rating": {
                    "category": "PG-13"
                }
            }
        ]
    }
}

Example payload for an ON_DEMAND TV show

{
    "payload": {
        "searchResults": [
            {
                "name": "The Big Bang Theory",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "The Big Bang Theory Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h 49m"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "series": {
                    "seasonNumber": "1",
                    "episodeNumber": "1",
                    "seriesName": "The Big Bang Theory",
                    "episodeName": "Pilot"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "Purchase Options",
                "reviews": [
                    {
                        "totalReviewCount": 41951,
                        "type": "FIVE_STAR",
                        "ratingDisplayString": "4.06"
                    }
                ],
                "rating": {
                    "category": "PG-13"
                }
            }
        ]
    }
}

Example payload for LIVE content

{
    "payload": {
        "searchResults": [
            {
                "name": "Interstellar",
                "contentType": "LIVE",
                "releaseYear": "2011",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "Interstellar Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h 30 min"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "Play Now",
                "rating": {
                    "category": "PG-13"
                },
                "networkDetails": [
                    {
                        "channel": {
                            "number": "1234",
                            "callSign": "PBS",
                            "affiliateCallSign": "KCTS9",
                            "uri": "someUrl"
                        },
                        "channelMetadata": {
                            "name": "Alternate Channel Name",
                            "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                        },
                        "airingDetails": [
                              {
                                  "isLiveBroadcast": "true"
                                  "end": "2018-01-24T02:30:00Z",
                                  "start": "2018-01-24T00:00:00Z"
                              }
                          ]
                    }
                ]
            }
        ]
    }
}

Example payload for content that can be browsed

{
    "payload": {
        "searchResults": [
            {
                "name": "The Big Bang Theory",
                "contentType": "RECORDING",
                "selectionAction": "BROWSE",
                "thumbnailImage": {
                    "contentDescription": "The Big Bang Theory Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "viewingDisplayString": "View episodes"
            }
        ]
    }
}
Field Description Required Type Values
SearchResults The list of search results. Yes List  
name The name of the video. Yes String Example: Interstellar
  contentType ContentType specifies the content type for the video that was returned in the search results. If you send a Recorded movie or TV show, the contentType is set to "RECORDING." If the result contains information about a live tv show, then the contentType is set to "LIVE." If the result contains an On Demand content, then the contentType is set to "ON_DEMAND." Yes Enum

RECORDING

LIVE

ON_DEMAND
  releaseYear Release year of video. This is used to display the release year when showing the item on the screen. No String Example: 2018
  selectionAction

Guidance on how to browse the entity when the user selects this item. For example, you may choose to group similar items together when sending the search results. Movies or TV shows can be grouped by Genre, or by Actor, etc. In such cases, you can drill down on the item by selecting the group and may view more results. 

The following enum values are allowed:

BROWSE - This means that you can get browse node items on the grouped entity to view more results. In this case, Alexa ends up calling the GetBrowseNodeItems on the selected entityId. 

PLAY - This means that the particular entity is not grouped and hence can be selected to play the item. In this case, Alexa ends up calling the GetPlayableItemsMetadata on the selected entityId.

 Yes Enum

BROWSE

PLAY
thumbnailImage Image information that is used to display an image for the result item on the screen. Yes Object { "contentDescription": "string", "sources": [ { "url": "string", "size": "string", "widthPixels": integer, "heightPixels": integer }, { "url": "string", "size": "string", "widthPixels": integer, "heightPixels": integer }, {...} ] }
runtime Details about the video runtime. No Object  
  runtimeInMilliseconds Duration of the video in milliseconds. No Long Example: 271871324
  displayString The formatted display string for the duration of the Video. This is used to show the duration on the screen. No String Example: "2h 30 m"
closedCaption Details about whether closed caption is available for the video and display information. No Object  
   status

Whether closed caption is available for the video. This is an enum with the following values:

AVAILABLE - This means that Closed caption is available for the video.

NOT_AVAILABLE - This means that Closed Caption is not available for the video.

 No Enum

AVAILABLE

NOT_AVAILABLE
  displayString The formatted display string to be shown on the screen for Closed caption.  No String Example: "CC"
series The metadata about the series if this item is part of a series. This information should be populated for TV shows only. If available, the information here is used to render  prompts to the user for example, "Here's 'The Big Bang Theory' Season 1, episode 4." No Object  
  episodeNumber Episode number of the video. No String Example: "1"
  seasonNumber Season number of the video. No String Example: "1"
  episodeName Episode title. No String Example: "1"
  seasonName Season title, if available. No String Example: "1"
absoluteViewingPositionMilliseconds Progress offset of video in milliseconds based on the user's watch history. If the user has watched it previously, this represents some offset greater than 0. This is used to display a progress bar on the result item indicating how much has the user watched previously. No Long Example: 1248625
parentalControl Parental Control information based on the user setting and the video. No Object  
  pinControl

This field indicates whether parental control is required for the user for this video based on the setting. This is an enum with 2 values.

REQUIRED - This means that parental control applies to this item based on the user's setting. When this is set, there is a lock icon displayed on the item to suggest that parental control applies to this item and the user is required to enter a PIN to view the video.

NOT_REQUIRED - This means that parental control does not apply to this item based on the user's setting.

 No Enum

REQUIRED

NOT_REQUIRED
viewingDisplayString The display string is shown on the screen with the result item and gives the user an indication of whether he/she can play immediately or has to go through buying/renting/subscribing, etc. Based on the entitlement status, the string can be different. The String needs to be localized based on the locale sent in the request. No String Example: "Play Now," "Subscribe."
reviews Information about the reviews for the video. No List  
  totalReviewCount Total count of reviews for the video. No Long Example: 13425
  type The type of review upon which information is based. No Enum FIVE_STAR
  ratingDisplayString Rating of the video based for the type mentioned above and the reviews. This is used to display the rating under each item in the search results. No String Example: "4.06"
rating Rating related information for the video. No Object  
  ratingCategory Rating category of the video. E.g. PG-13. This is rating that applies for the region that this Video is resolved from. Also the rating value may differ based on the content for example, for movies, you may send us an MPAA rating like "PG-13" or for TV shows, you may send us a TV parental guidelines rating like "TV-PG."  No String

Example: "PG-13"

Example: "TV-PG"
networkDetails If the result item represents a live show (contentType = LIVE) on a channel, this object contains its metadata. No List  
  channel Information about the channel the Video is currently airing on. No Object  
  channelMetadata Metadata information about the channel. No Object  
airingDetails This object contains information on when content airs. No List
  end End time of the Video. String containing a time in ISO 8601 format. Yes String Example: "2016-09-07T23:59:00+00:00"
  start Start time of the video. String containing a time in ISO 8601 format. Yes String Example: "2016-09-07T23:59:00+00:00"
isLiveBroadcast Whether this content is airing in real time. No boolean true, false

BROWSE

GetBrowseNodeItems

When search Results are shown on the screen, you may choose to combine similar items together into a logical group. For example, for an utterance like "Show me my recordings," you may group TV shows into one and Movies into another group. When the users select a group, they can then view more results from that group. This directive is sent for cases when the user wants to drill down into a specific browse node item as determined by selectionAction field in the GetDisplayableItems response. If the value of the field is BROWSE, you have more search results to show on the screen when the users select this item on the device. Once the user selects the Video, Alexa sends a GetBrowseNodeItems directive to get more mediaIdentifiers, and then send a GetDisplayableItemsMetadata directive for those items to display results on the screen. If the value of the selectionAction field is set to PLAY, you need to play that item if the user selects it. In such cases, Alexa sends a GetPlayableItemsMetadata directive.

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetBrowseNodeItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "mediaIdentifier": {
                "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
            }
        }
    }
}

Response:

The response contains the list of the Ids for the items in the requested group.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetBrowseNodeItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}

PAGINATION

GetNextPage

After receiving search results from the content provider, a user may want to see additional search results, or "the next page" of search results. For this purpose, the Lambda receives the GetNextPage directive. The following examples show requests and responses.

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetNextPage",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "cookie": {

            },
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "minResultLimit": 8,
            "maxResultLimit": 25
        }
    }
}
Field Description Required Type Values
nextToken Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests. No String Opaque String
minResultLimit

The minimum number of results to return in this call for which a pageToken is accepted. 

If you return less than the `minResultLimit` field along with a `pageToken` to fetch more results, then Alexa does not consider the `pageToken` to fetch the new items and only displays whatever Alexa received.

For a `pageToken` to be considered for fetching more results, the number of items have to match at least the value in `minResultLimit`, however, the number of items can be more than `minResultLimit` up to a max of `maxResultLimit`. If the number of items is more than the `maxResultLimit`, then Alexa discards the items after the `maxResultLimit`.

 Yes Integer Example: 8
maxResultLimit A limit to the maximum number of results to return in this call. See description of `minResultLimit` field for more details. Yes Integer Example: 25

Response:

The response in this case is the list of items to display on the device. This payload follows the same format as the one for the earlier search request.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetNextPageResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Alexa-access-token"
            },
            "endpointId": "appliance-001"
        },
        "payload": {
            "nextToken": "qefjrfiugef74",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}
Field Description Required Type Values
nextToken Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests. No String opaque string
mediaItems A list of mediaIdentifiers for the videos that is shown as search results on the screen. Yes List  
mediaIdentifier Identifier for the mediaItem. Yes Object  
id An identifier for the video item that is used to fetch any display or playback related metadata information on subsequent calls to GetDisplayableItemsMetadata or GetPlayableItemsMetadata. This identifier is opaque to Alexa and is just used as is when querying for metadata information. Yes String opaque string

QUICK PLAY

GetPlayableItems

Request:

The GetPlayableItems request is identical to the previously mentioned GetDisplayableItems except for the header name. This API is used when the user is asking to play content on the device. Having separate APIs for play and search allows for greater transparency around user intent. 

The following general guidance shows how to perform the search in different scenarios:

Video Name: For example, consider - "Play Interstellar."

  • In the instance where a video name is present, Alexa sends a GetPlayableItems directive with all the relevant video names found in the content provider catalog, with catalog IDs included in the externalIds field. You should favor the content based on the IDs sent to you along with the videoNames and select the one that can be played and return that item. Note that in this case, Alexa found the matching titles from the catalog, so there should not be a need to do another search again. You can use the information sent to you in the request to select the correct video.

Genre/Actor: Play a comedy movie or Play an action movie with Tom Cruise 

  • In the instance where a video name is not present and some other slot like genre and/or actor is present, Alexa sends a GetPlayableItems directive, and you should do a search using the entities sent in the request. For example, for "Play an action movie," you receive {mediaType: MOVIE, genreName: COMEDY}, and can search based on these criteria and return an identifier for a comedy movie. Similarly for "Play an action movie with Tom Cruise," you receive {mediaType: MOVIE, genreName: ACTION, actorName: Tom Cruise}, and then you can search and return an identifier for a movie that matches those criteria. Once the identifier is returned in the response, Alexa sends a GetPlayableItemsMetadata directive to fetch additional metadata.
{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetPlayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Video",
                    "value": "Manchester by the Sea",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "en-US",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}
Field Description Required Type Values
entities A list of entity objects to search.  Yes List  
  type Entity types for video content. For information about video content entity types, see Entity Types for Video Content in the Video Skill API Reference. Yes String MOVIE, TV SHOW, ACTOR, GENRE, etc
  value The value of the entity. Yes String Interstellar
 externalIds External identifiers for the entity, key is the provider, value is the id.  No Map

key = "gracenote" or "gti" 

Value: ""SH000000012"
minResultLimit

The minimum number of results to return in this call for which a `pageToken` is accepted. 

If you return less than the `minResultLimit` field along with a `pageToken` to fetch more results, then Alexa does not consider the `pageToken` to fetch the new items and only displays whatever Alexa received.

For a `pageToken` to be considered for fetching more results, the number of items have to match at least the value in `minResultLimit`, however, the number of items can be more than `minResultLimit` up to to a max of `maxResultLimit`. If the number of items is more than the `maxResultLimit`, then Alexa discards the items after the `maxResultLimit`.

 Yes Integer Example: 8
maxResultLimit A limit to the maximum number of results to return in this call. See description of `minResultLimit` field for more details. Yes Integer Example: 25
timeWindow

Provides the start and end times that the request should act on. This is usually used for Live TV or Recording only and not for On Demand content. Generally, if the time window is available and can be used to filter the results, the content provider should use it.

For providers that only search for On Demand content, the time window field is usually set to null and can be ignored.

For Live TV or Recording, if the user specifies the time window, for example, "Search for TV shows between 4 and 5 pm," or "Find TV shows recorded last week," then you should filter the results based on the start and end times whenever available.

Depending on the capabilities, either both the fields—"start" and "end"—can be present, or any one field can be present. For example, for "Search TV shows between 4 and 5 pm," both the fields are present. For "Show me TV shows starting at 5 pm," only "start" field is populated while "end" is null.

   Object  
  start The start time of the time window. String containing a time in ISO 8601 format. No String 2016-09-07T23:59:00+00:00
  end The end time of the time window. String containing a time in ISO 8601 format. No String 2016-09-07T23:59:00+00:00
  contentType `ContentType` specifies the content category to be searched. Note that this is different from `mediaType` in the entitles. `MediaType` specifies the type of media to search for. For example, Movies, or TV shows, etc. Therefore, if the user is interested in browsing recorded movies, he/she says something like "Show me recorded movies." In this case, the `mediaType` is set to "MOVIE," while `contentType` is set to "RECORDING." Similarly when the user wants to Browse live tv content, he/she says something like "Show me what’s on now," and in this case the `contentType` is set to "LIVE."  No Enum

RECORDING

LIVE

ON_DEMAND
locale The locale for the user that should be used to get displayable information for the search results. A locale in the same format specified for languages in in the Network Working Group Best Current Practice 47 (BCP-47). For more information, see the BCP-47 document. Yes String en-US, en-GB, de-DE

Response: 

The response structure in this case is similar to the response returned for the GetDisplayableItems API.

The following guidelines explain the type of response this API returns: 

  • The goal of this API is to get a single item that can be played for the request. 

  • If there is only one item to play, you can just return that one item and Alexa ends up playing that item. 

  • For some quickplay capabilities, you can choose to return multiple items in the response and have the user choose which one to play. For example, for "Play Star Wars," there can be multiple movies in the Star Wars franchise returned in the response or movies and TV shows pertaining to Star Wars as well. If and when you return multiple results, the number of results returned in the first call should not exceed the resultLimit parameter specified in the request. In such cases, once the content provider returns multiple results, Alexa Video sends a GetDisplayableItemsMetadata directive to fetch the metadata and display search results.

  • If the only result found is not playable because the user is not entitled to play the title or because a subscription is required, then you can return that one item. Alexa fetches metadata and renders a prompt to either buy or rent or subscribe once Alexa finds that this item is not playable. After that, the user can trigger the purchase workflow to buy/rent the title and play it afterwards.

  • If multiple results are found that are not playable, then you can choose to return all the results, and Alexa either disambiguates or renders an informational prompt to buy, rent, or subscribe.

  • If multiple results are found, with some playable and some not, then you should favor the playable one and return the playable result so that it can be played on the device.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetPlayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}
Field Description Required Type Values
nextToken Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests. No String opaque string
mediaItems A list of mediaIdentifiers for the videos that is shown as search results on the screen. Yes List  
mediaIdentifiers Identifier for the mediaItem. Yes Object  
id An identifier for the video item that is used to fetch any display or playback related metadata information on subsequent calls to GetDisplayableItemsMetadata or GetPlayableItemsMetadata. This identifier is opaque to Alexa and is just used as is when querying for metadata information. Yes String opaque string

GetPlayableItemsMetadata

Request: 

Similar to GetDisplayableItemsMetadata discussed before, the request only contains a list of entity IDs that Alexa needs metadata for. The entity IDs are returned by the provider from a previous GetPlayableItems call that happened for the request.

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetPlayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {        
            }
        },
        "payload": {
            "locale": "en-US",  
            "mediaIdentifier": {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                }
        }
    }
}

Response:

The response in this case should only contain metadata information required for playback and for rendering any success prompts before playing the video. The metadata in the response for this API should never contain any metadata specific to displaying information on the screen unless that metadata is required for prompting.

Example response for an ON_DEMAND TV show

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "ON_DEMAND",
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "playbackContextToken": "provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "absoluteViewingPositionMilliseconds": 1232340
                }
            ]
        }
    }
}

Example response for a LIVE movie

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}
Field Description Required Type Values
name The name of the Video. This is used to render a prompt to the user about the video that is going to be played. For example, "Here's *Interstellar*." Yes String Interstellar
contentType

`ContentType` specifies the content category to be searched. Note that this is different from `mediaType` in the entitles. `MediaType` specifies the type of media to search for. For example, Movies, or TV shows, etc. Therefore, if the user is interested in browsing recorded movies, then `mediaType` is set to "MOVIE," while `contentType` is set to "RECORDING." 

This is also used to render a prompt to the user. For example, if the `contentType` is LIVE, Alexa renders a prompt like "Here's the Academy Awards now airing on CBS, from your DVR." If the `contentType` is RECORDING, Alexa renders a prompt like "Here's the Academy Awards from your DVR."

 Yes Enum

RECORDING

LIVE

ON_DEMAND
series The metadata about the series if this item is part of a series. If present, the information here is used only for rendering a prompt to the user with the details about the season and episode. For example something like "Here’s 'The Big Bang Theory' Season 1, Episode 8." No Object  
   seasonNumber The season number of the video. No String 1
    episodeNumber The episode number of the video. No String 3
   episodeName The episode name. No String 4
   seasonName The season name. No String 2
playbackContextToken Token that allows mapping of entities back to your system for further identification. You can send any string identifier as long as you can map it back to identify an entity on your side. This token is opaque to Alexa and is sent to device for playback purposes. This can be the same media identifier that was used to fetch the metadata information if that is what is needed for playback or this can be a different serialized string with additional information that is required for playback. Yes String Opaque string
parentalControl Parental Control information based on the user and the video. Yes Object  
  pinControl

This field indicates whether parental control is required for the user for this video based on the setting. This is an enum with 2 values.

REQUIRED - This means that parental control applies to this item based on the user's setting. When this is set, there is a lock icon displayed on the item to suggest that parental control applies to this item and the user is required to enter a PIN to view the video.

NOT_REQUIRED - This means that parental control does not apply to this item based on the user's setting.

 Yes Enum

REQUIRED

NOT_REQUIRED
absoluteViewingPositionMilliseconds Progress offset of video in milliseconds based on the user's watch history. If the user has watched it previously, this represents some offset greater than 0. This is used to display a progress bar on the result item indicating how much has the user watched previously. Yes Long Example: 1248625
networkDetails If the result item represents a live show on a channel, this object contains the metadata information for it. Whenever available, the information here is used to render a prompt to the user giving details about the channel the video is currently airing along with the start and end times. No List  
 channel Information about the channel the Video is currently airing on. No Object  
channelMetadata Metadata information about the channel. No Object  
airingDetails This object contains information on when content airs. No List
end End time of the Video. String containing a time in ISO 8601 format. No String 2018-01-24T02:30:00Z
start Start time of the program. String containing a time in ISO 8601 format. No String 2018-01-24T02:30:00Z
isLiveBroadcast Whether this content is airing in real time. No boolean true, false

CHANNEL NAVIGATION

GetPlayableItems

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetPlayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Channel",
                    "value": "PBS",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    },
                    "entityMetadata": {
                        "channelCallSign": "KBTC",
                        "channelNumber": "123"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "en-US",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}
Field Description Required Type Values
entities A list of entity objects to search.  Yes List  
  type Entity types for video content. For information about video content entity types, see Entity Types for Video Content in the Video Skill API Reference. Yes String MOVIE, TV SHOW, ACTOR, GENRE, etc
  value The value of the entity. Yes String Interstellar
 externalIds External identifiers for the entity, key is the provider, value is the id.  No Map

key = "gracenote" or "gti" 

Value: ""SH000000012"
minResultLimit

The minimum number of results to return in this call for which a `pageToken` is accepted. 

If you return less than the `minResultLimit` field along with a `pageToken` to fetch more results, then Alexa does not consider the `pageToken` to fetch the new items and only displays whatever Alexa received.

For a `pageToken` to be considered for fetching more results, the number of items have to match at least the value in `minResultLimit`. However, the number of items can be more than `minResultLimit` up to a max of `maxResultLimit`. If the number of items is more than the `maxResultLimit`, then Alexa discards the items after the `maxResultLimit`.

 Yes Integer Example: 8
maxResultLimit A limit to the maximum number of results to return in this call. See description of `minResultLimit` field for more details. Yes Integer Example: 25
timeWindow

Provides the start and end times that the request should act on. This is usually used for Live TV or Recording only and not for On Demand content. Generally, if the time window is available and can be used to filter the results, you should use it.

For providers that only search for On Demand content, the time window field is usually be set to null and can be ignored.

For Live TV or Recording, if the user specifies the time window, for example, "Search for TV shows between 4 and 5 pm," or "Find TV shows recorded last week," then you should filter the results based on the start and end times whenever available.

Depending on the capabilities, either both the fields—"start" and "end"—can be present, or any one field can be present. For example for "Search TV shows between 4 and 5 pm," both the fields are present. For "Show me TV shows starting at 5 pm," only the "start" field is populated while "end" is null.

   Object  
  start The start time of the time window. String containing a time in ISO 8601 format. No String 2016-09-07T23:59:00+00:00
  end The end time of the time window. String containing a time in ISO 8601 format. No String 2016-09-07T23:59:00+00:00
  contentType `ContentType` specifies the content category to be searched. Note that this is different from `mediaType` in the entitles. `MediaType` specifies the type of media to search for. For example, Movies, or TV shows, etc. Therefore, if the user is interested in browsing recorded movies, he/she says something like "Show me recorded movies." In this case, the `mediaType` is set to "MOVIE," while `contentType` is set to "RECORDING." Similarly when the user wants to Browse live tv content, he/she says something like "Show me what’s on now," and in this case the `contentType` is set to "LIVE."  No Enum

RECORDING

LIVE

ON_DEMAND
locale The locale for the user that should be used to get displayable information for the search results. A locale in the same format specified for languages in in the Network Working Group Best Current Practice 47 (BCP-47). For more information, see the BCP-47 document. Yes String en-US, en-GB, de-DE

Channel Entity Structure:

Channel represents the identifying data for a television channel; for example, "PBS" might contain the following:

Field Description Type Example
externalIds A map of external identifiers for this entity, key is the provider, value is the id. Object  
Gracenote The external Gracenote identifier. String ST0000000666661
entityMetadata A map of meta data associated with the channel. Object  
channelNumber The channel number. Integer 1234
channelCallSign The call sign for the channel. String KBTC
value The name of the channel. String PBS

Response: 

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetPlayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}
Field Description Required Type Values
nextToken Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests. No String opaque string
mediaItems A list of mediaIdentifiers for the videos that is shown as search results on the screen. Yes List  
mediaIdentifiers Identifier for the mediaItem. Yes Object  
id An identifier for the video item that is used to fetch any display or playback related metadata information on subsequent calls to GetDisplayableItemsMetadata or GetPlayableItemsMetadata. This identifier is opaque to Alexa and is just used as is when querying for metadata information. Yes String opaque string

GetPlayableItemsMetadata

Request: 

Similar to GetDisplayableItemsMetadata discussed before, the request only contains a list of entity IDs that Alexa needs metadata for. This call usually contains entity IDs from a previous GetPlayableItems call. You should return metadata for those entity IDs.

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetPlayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {        
            }
        },
        "payload": {
            "locale": "en-US",  
            "mediaIdentifier": {
                    "id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
                }
        }
    }
}

Response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}
Field Description Required Type Values
name The name of the Video. This is used to render a prompt to the user about the video that is going to be played. For example, "Here's *Interstellar*." Yes String Interstellar
contentType

`ContentType` specifies the content category to be searched. Note that this is different from `mediaType` in the entitles. `MediaType` specifies the type of media to search for. For example, Movies, or TV shows, etc. Therefore, if the user is interested in browsing recorded movies, then `mediaType` is set to "MOVIE," while `contentType` is set to "RECORDING." 

This is also used to render a prompt to the user. For example, if the `contentType` is LIVE, Alexa renders a prompt like "Here's the Academy Awards now airing on CBS, from your DVR." If the `contentType` is RECORDING, Alexa renders a prompt like "Here's the Academy Awards from your DVR."

 Yes Enum

RECORDING

LIVE

ON_DEMAND
series The metadata about the series, if this item is part of a series. If present, the information here is used only for rendering a prompt to the user with the details about the season and episode. For example something like "Here's 'The Big Bang Theory' Season 1, Episode 8." No Object  
   seasonNumber The season number of the video. No String 1
    episodeNumber The episode number of the video. No String 3
   episodeName The episode name. No String 4
   seasonName The season name. No String 2
playbackContextToken Token that allows mapping of entities back to your system for further identification. You can send any string identifier as long as you can map it back to identify an entity on their side. This token is opaque to us and is sent to the device for playback purposes. This can be the same media identifier that was used to fetch the metadata information if that is what is needed for playback or this can be a different serialized string with additional information that is required for playback. Yes String Opaque string
parentalControl Parental Control information based on the user and the video. Yes Object  
  pinControl

This field indicates whether parental control is required for the user for this video based on the setting. This is an enum with 2 values.

REQUIRED - This means that parental control applies to this item based on the user's setting. When this is set, a lock icon is displayed on the item to suggest that parental control applies to this item and the user is required to enter a PIN to view the video.

NOT_REQUIRED - This means that parental control does not apply to this item based on the user's setting.

 Yes Enum

REQUIRED

NOT_REQUIRED
absoluteViewingPositionMilliseconds Progress offset of video in milliseconds based on the user's watch history. If the user has watched it previously, this represents some offset greater than 0. This is used to display a progress bar on the result item indicating how much has the user watched previously. Yes Long Example: 1248625
networkDetails If the result item represents a live show on a channel, this object contains its metadata. Whenever available, the information here is used to render a prompt to the user giving details about the channel the video is currently airing along with the start and end times. No List  
 channel Information about the channel the Video is currently airing on. No Object  
channelMetadata Metadata information about the channel. No Object  
airingDetails This object contains information on when content airs. No List
end End time of the Video. String containing a time in ISO 8601 format. No String 2018-01-24T02:30:00Z
start Start time of the program. String containing a time in ISO 8601 format. No String 2018-01-24T02:30:00Z
isLiveBroadcast Whether this content is airing in real time. No boolean true, false

ERROR HANDLING

In the event of an error, you should return an error code in the response so that Alexa can take a specific action. For information about the structure of the response, see Alexa.Video.ErrorResponse in the Video Skill API Reference. This already includes an error type for NOT_SUBSCRIBED that can be used for non-entitled content.

For information about more general errors, see Alexa.ErrorResponse Interface in the Capability Interface Reference.

For video skills on Echo Show, the following error should be used when no search results are found:

Error type Description
CONTENT_NOT_FOUND This value should be used to indicate that no content was found based on the criteria sent in the request or that the content was not recognized by the content provider.

Sample response for Error case:

{
    "event": {
        "header": {
            "messageId": "4e02d3c8-85e8-4e32-8a1b-08c1d52122ad",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/==",
            "name": "ErrorResponse",
            "namespace": "Alexa.Video",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "DirectedUserId",
                "directedUserId": "access-token-from-Amazon"
            },
            "endpointId": "videoDevice-001"
        },
        "payload": {
            "message": "optional information about the error that will be logged by Alexa",
            "type": "CONTENT_NOT_FOUND"
        }
    }
}

LANDING PAGE

Alexa renders a landing page for your content when the user says a phrase such as "open your app name." Alexa renders this page using the previously discussed search, browse, and pagination APIs, but there are specific nuances specific to landing page, which are detailed here. This section provides sample requests and responses to landing-page-specific directives, as well as clarification of how these directives and responses are distinct from other similar directives.

GetDisplayableItems

For GetDisplayableItems directives used for populating your landing page, ASK has added an additional field called itemType with enum values VIDEO and CATEGORY. The itemType field specifies the type of search to complete. The following examples show directives and responses for both values.

Field Description Required Type Values
 itemType itemType specifies the type of item to be searched. No Enum

VIDEO

CATEGORY

Request:

{
   "directive": {
       "header": {
           "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
           "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
           "name": "GetDisplayableItems",
           "namespace": "Alexa.VideoContentProvider",
           "payloadVersion": "3"
        },
       "endpoint": {
           "scope": {
               "type": "BearerToken",
               "token": "access-token-from-skill"
            },
           "endpointId": "videoDevice-001",
           "cookie": {

            }
        },
       "payload": {
           "entities": [
                {
                   "type": "SORTTYPE",
                   "value": "RECOMMENDED"
                }
            ],
           "itemType" : "VIDEO",
           "locale": "en-US",
           "minResultLimit": 1,
           "maxResultLimit": 1        
        }
    }
}

Response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetDisplayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e"
                    }
                }
            ]
        }
    }
}

Request:

{
   "directive": {
       "header": {
           "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
           "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
           "name": "GetDisplayableItems",
           "namespace": "Alexa.VideoContentProvider",
           "payloadVersion": "3"
        },
       "endpoint": {
           "scope": {
               "type": "BearerToken",
               "token": "access-token-from-skill"
            },
           "endpointId": "videoDevice-001",
           "cookie": {

            }
        },
       "payload": {
           "entities": [
                {
                   "type": "SORTTYPE",
                   "value": "RECOMMENDED"
                }
            ],
           "itemType" : "CATEGORY",
           "locale": "en-US",
           "minResultLimit": 5,
           "maxResultLimit": 5        
        }
    }
}

Response

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetDisplayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/myWatchList"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/primeOriginals"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/popularMovies"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/newReleases"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/liveTV"
                    }
                }
            ]
        }
    }
}

GetDisplayableItemsMetadata

For GetDisplayableItemsMetadata directives used to populate your landing page, ASK has also added the itemType field, with the same enum values. The following examples show sample directives and responses.

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetDisplayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {        
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifiers": [
                {
                    "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e"
                },
                {
                    "id": "entity://provider/category/myWatchList"
                },
                {
                    "id": "entity://provider/category/primeOriginals"
                },
                {
                    "id": "entity://provider/category/popularMovies"
                },
                {
                    "id": "entity://provider/category/newReleases"
                },
                {
                    "id": "entity://provider/category/liveTV"
                }
            ]
        }
    }
}

Response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetDisplayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "resultsTitle": "Search Results",
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "ON_DEMAND",
                    "itemType": "VIDEO",
                    "releaseYear": "2014",
                    "selectionAction": "PLAY",
                    "thumbnailImage": {
                        "contentDescription": "Interstellar Image",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_LARGE",
                                "widthPixels": 1920,
                                "heightPixels": 1280
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "2h 49m"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Purchase Options",
                    "reviews": [
                        {
                            "totalReviewCount": 41951,
                            "type": "FIVE_STAR",
                            "ratingDisplayString": "4.06"
                        }
                    ],
                    "rating": {
                        "category": "PG-13"
                    },
                    "mediaIdentifier": {
                        "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e"
                    }
                },
                {
                    "name": "My Watchlist",
                    "contentType": "ON_DEMAND",
                    "itemType": "CATEGORY",
                    "selectionAction": "BROWSE",
                    "thumbnailImage": {
                        "contentDescription": "My Watchlist Image",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "mediaIdentifier": {
                        "id": "entity://provider/category/myWatchList"
                    }
                }
            ]
        }
    }
}

GetNextPage

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetNextPage",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "cookie": {

            },
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "minResultLimit": 9,
            "maxResultLimit": 25
        }
    }
}

Response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetNextPageResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Alexa-access-token"
            },
            "endpointId": "appliance-001"
        },
        "payload": {
            "nextToken": "qefjrfiugef74",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/watchNext"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/includedOnPrime"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/popularMovies"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/featuredTV"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/dramaMovies"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/liveTV"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/primeOriginals"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/popularTV"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "entity://provider/category/recentlyAdded"
                    }
                }
            ]
        }
    }
}

GetBrowseNodeItems

Request:

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetBrowseNodeItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {        
            }
        },
        "payload": {
            "mediaIdentifier": {
                    "id": "entity://provider/category/bingeableTV"
                }
        }
    }
}

Response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetBrowseNodeItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333f"
                    }
                }
            ]
        }
    }
}

GetDisplayableItemsMetadata

Request:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetDisplayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {        
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifiers": [
                {
                    "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e"
                },
                {
                    "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333f"
                }
            ]
        }
    }
}

Response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetDisplayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "resultsTitle": "Search Results",
            "searchResults": [
                {
                    "name": "The Big Bang Theory",
                    "contentType": "ON_DEMAND",
                    "itemType": "VIDEO",
                    "releaseYear": "2014",
                    "selectionAction": "BROWSE",
                    "thumbnailImage": {
                        "contentDescription": "The Big Bang Theory Image",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "2h 49m"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Purchase Options",
                    "reviews": [
                        {
                            "totalReviewCount": 41951,
                            "type": "FIVE_STAR",
                            "ratingDisplayString": "4.06"
                        }
                    ],
                    "rating": {
                        "category": "PG-13"
                    },
                    "mediaIdentifier": {
                        "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e"
                    }
                },
                {
                    "name": "The Big Bang Theory",
                    "contentType": "LIVE",
                    "itemType": "VIDEO",
                    "releaseYear": "2011",
                    "selectionAction": "PLAY",
                    "thumbnailImage": {
                        "contentDescription": "The Big Bang Theory Image ",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "30 min"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Play Now",
                    "rating": {
                        "category": "TV-PG"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "number": "1234",
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9",
                                "uri": "someUrl"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name",
                                "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                            },
                            "airingDetails": [
   {
      "isLiveBroadcast": "true"
                                   "end": "2018-01-24T02:30:00Z",
                                   "start": "2018-01-24T00:00:00Z"
                                },
		]
                        }
                    ],
                    "mediaIdentifier": {
                        "id": "gti://provider1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333f"
                    }
                }
            ]
        }
    }
}

BADGING

It is often useful to have badges, or contextual images, on search result tiles or over video playback to provide useful information to the user. This section covers the types of badges available, as well as their intended purpose.

Badges

The following table shows the types of display badges you can implement.

Badge type Description
Recording This badge is displayed when the user is actively recording the content. This badge takes precedence over all other badges.
Live This badge is displayed when the content is currently airing in real time (i.e. shows such as the Oscars, Emmys, and sports games).
On Now This badge is displayed when the content is airing on a channel at a given time, and is not considered Live.

In addition to badges, you should also show the Network logo or the Network call sign, which indicates where this piece of content is airing. For example, let’s say you say "Show me comedy TV shows on provider." In such cases, provider can show content from multiple networks, such as ABC, HBO, CBS, etc. When you return such results on an Echo Show device, you should also show a network logo on the bottom of the box art to indicate the origin of the content. If the network logo is not available, you should show the network call sign, such as ABC, HBO, etc. 

Content Freshness

You should also indicate whether the content is "new" with the search results metadata. This information comes from content providers and is displayed to indicate that this content is airing for the first time. For example, if you search for episodes of "The Big Bang Theory," and episodes 1-5 were aired already and now episode 6 is available to view, content providers should let you know so that you can display "NEW" along with other metadata for that episode. 

You can specify badging in your skill through the GetDisplayableItemsMetadata and GetPlayableItemsMetadata APIs. 

Badging APIs

To support badging, you should use the following structures within the GetDisplayableItemsMetadata response payload: 

  • "recording" - used to indicate if content is currently being recorded.

  • "contentFreshness" - used to indicate whether the content is new.

  • "networkDetails" - used to specify channel metadata.

  • "airingDetails" – used to specify start and end times as well as whether content is airing live.

GetDisplayableItemsMetadata

Sample response:

{
    "payload": {
        "searchResults": [
            {
                "name": "Interstellar",
                "contentType": "LIVE",
                "releaseYear": "2011",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "InterstellarImage",
                    "sources": [
                        {
                            "url": "http: //ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h30min"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "PlayNow",
                "rating": {
                    "category": "PG-13"
                },
                "recording": {
                    "status": "RECORDING"
                },
                "contentFreshness": {
                    "state": "NEW"
                },
                "networkDetails": [
                    {
                        "channel": {
                            "number": "1234",
                            "callSign": "PBS",
                            "affiliateCallSign": "KCTS9",
                            "uri": "someUrl"
                        },
                        "channelMetadata": {
                            "name": "AlternateChannelName",
                            "image": "http: //ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                        },
                        "airingDetails": [
                            {
                                "isLiveBroadcast": "true",
                                "end": "2018-01-24T02: 30: 00Z",
                                "start": "2018-01-24T00: 00: 00Z"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
Field Description Required Type Values
recording Information related to recording. The current structure only has a single field for 'status'. The reason for making this a structure and not a standalone field is because ASK may want to add some more information to the recording structure in the future. Having it available as an object allows ASK to group these items and make it extensible for the future requirements. No Object
recording.status

Recording status for the content. The following enum values are allowed:

RECORDED - This means that the content was previously recorded.

RECORDING - This means that the content is being actively recorded at the time of the request.

SCHEDULED - This means that the content is scheduled to be recorded at a future time.

 No String

RECORDED

RECORDING

SCHEDULED
contentFreshness

Details about content freshness. This object also has a single field for 'state.' Similar to the previous field, ASK can extend this and add more states in the future in addition to the one added as part of this review.

In the future, this object may be expanded to add more details related to contentFreshness.

 No Object
contentFreshness.state

Whether this content is new for the provider that Alexa is fetching results from.

The following enum values are allowed:

NEW - This means that the content is new and/airing for the first time on the provider.

 No String NEW
networkDetails

Network details gives information about the network the program is airing from. For example, a new episode of "The Big Bang Theory" airing from CBS, or a live soccer game airing from ESPN.

For On Demand content, this could Prime Video displaying Game of thrones results from HBO for example.

 No List
airingDetails.isLiveBroadcast

Whether this content is airing in real time.

This must be set to true for live events like Watching an NFL football game, or award shows like Oscars or Emmys, etc that are happening in real time.

This must be set to false for content that was filmed prior to the original airing time. For example, a new episode of Big bang theory that airs every Thursday. This must also be set to false for content that was once streamed in real time, like a football game in the past, but is no longer happening in real time.

 No boolean true, false

GetPlayableItemsMetadata

The same networkDetails structure used in GetDisplayableItemsMetadata is also used for GetPlayableItemsMetadata.

Sample response:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "amzn1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "AlternateChannelName"
                            },
                            "airingDetails": [
                                {
                                    "isLiveBroadcast": "true",
                                    "end": "2018-01-24T02: 30: 00Z",
                                    "start": "2018-01-24T00: 00: 00Z"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}