GetDisplayableItems directive to your Lambda.
The following diagram shows the expected Alexa directive and Lambda response;
Utterances for GetDisplayableItems
Alexa sends aGetDisplayableItems directive to your Lambda when users say the following utterances.
Handling GetDisplayableItems Directives
When users search for content using criteria likeVideoName, ActorName, GenreName, etc., Alexa sends a GetDisplayableItems directive to retrieve content to display.
Your Lambda response (GetDisplayableItemsResponse) should contain basic identifying information about the content that matches the user’s search request. Your response should not contain additional metadata such as images, etc.
Note that Alexa supports non-title requests such as “Alexa, find a comedy on <video provider>” or “Alexa, find football on <video provider>.” For these requests, the expectation is that you conduct a search within your catalog and return a list of titles that matches the search request. Leverage any personalization algorithms you may have to bias the result to the user.
If you cannot find any results matching the user’s request and return zero results in your response, you receive a second GetDisplayableItems directive with the SORTTYPE = RECOMMENDED. You can then return a set of recommended videos to the user in your response. Alexa tells the user that there are no search results, but that Alexa recommends this content to the user.
GetDisplayableItems Example
The following is an example of aGetDisplayableItems directive:
GetDisplayableItems Example (Landing Page)
When a user opens the provider landing page, Alexa sends twoGetDisplayableItems directives.
- The first directive is to retrieve categories for the landing page by setting the
itemTypeproperty toCATEGORYand including aSORTTYPEofRECOMMENDED. - The second directive obtains the featured video for the landing page where the directive sets the
itemTypetoVIDEOinstead.
GetDisplayableItemsMetadata call with a list combined of Category IDs and Video ID. The response includes metadata about the video as well as the categories.
The following shows an example of a GetDisplayableItems directive used for a landing page:
itemType specifies the type of item to be searched. The values can be either VIDEO or CATEGORY.
Payload Descriptions
The following table defines thepayload fields for GetDisplayableItems directives.
| Field | Description | Data Type |
|---|---|---|
entitiesrequired | 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 directive. If in doubt, 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.entities with a type: Channel contain identifying data for a television channel. For example: | List |
typerequired | Entity types for video content. For a list of video content entity types, see Entity Types.Examples: MediaType, video, Actor, Genre, Franchise, Season, Episode | String |
valuerequired | The value of the entity. For channels, the name of the channel.Examples: Interstellar, PBS | String |
itemTyperequired | itemType specifies the type of item to be searched. itemType is unique for GetDisplayableItems directives related to the landing page template. When a user opens your landing page (by saying “Alexa, open ACME video” or by saying “Video Home” and then selecting your video skill), Alexa sends two GetDisplayableItems directives:
GetDisplayableItemsResponse) for both directives, Alexa sends one GetDisplayableItemsMetadata call with a list combined of Category IDs and Video ID. The response includes metadata about the video as well as the categories.Example: VIDEO, CATEGORY | Enum |
externalIdsoptional | A map of external identifiers for this entity; key is the provider, value is the id.Examples: key = gti, value = SH000000012 | Object |
imdboptional | The external IMDB identifier.Example: tt4574334 | String |
contentTyperequired | 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.ContentType is also used to render a prompt to the user. For example, if the contentType is LIVE, Alexa renders a prompt such as, “Here’s the Academy Awards now airing on CBS.” If the contentType is RECORDING, Alexa renders a prompt such as, “Here’s the Academy Awards.”Examples: RECORDING, LIVE, ON_DEMAND | Enum |
localerequired | 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). If you receive an unrecognized locale, default to en-US.Examples: en-US, en-GB, de-DE | String |
minResultLimitrequired | 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, Alexa discards the items after the maxResultLimit.Example: 8 | Integer |
maxResultLimitrequired | A limit to the maximum number of results to return. See description of minResultLimit field for more details.Example: 25 | Integer |
timeWindowoptional | 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 containing start and end times. |
startoptional | The start time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z | A string in ISO 8601 format. |
endoptional | The end time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z | A string in ISO 8601 format. |
Entity Types
Theentities object consists of a list of objects, each of which contains a type and a value along with other possible data such as external IDs. The following values are possible for the type value: Actor, App, Channel, Character, Director, Episode, Event, Franchise, Genre, League, MediaType, ProductionCompany, Season, Sport, SportsTeam, Video, Popularity, Recency, and VideoResolution. Details about the payloads for each entity type are provided in the sections below.
Actor
Actor represents an actor credited in video media content; for example, Casey Affleck might contain the following:
+
+
| Actor Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ ASIN | The external ASIN of this entity | String | B01LTHZVKG |
└─ imdb | The IMDB identifier for the actor. | String | tt4034228 |
uri | URI mapping to the actor/actress | URI | entity://provider/actor/caseyaffleck |
value | The name of the actor | String | Casey Affleck |
App
App represents the explicit app name specified by the user in utterance; for example, “Manchester by the Sea on Prime” might contain the following:
+
+
Channel
Channel represents the identifying data for a television channel; for example, “PBS” might contain the following:
+
+
| Channel Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The external IMDB identifier | String | tt4034228 |
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 |
uri | The URI of the channel | URI | entity://provider/channel/1234 |
value | The name of the channel | String | PBS |
Character
ACharacter represented in video media content.
+
+
| Character Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ ASIN | The Amazon Standard Identification Number (ASIN) for this entity | String | B00DT55P3K |
└─ imdb | The IMDB identifier for the character. | String | character id |
uri | URI mapping to the character | URI | entity://provider/character/snowwhite |
value | The name of the character | String | Snow White |
Director
Director represents the director name for the video media content; for example, “Kenneth Lonergan” might contain the following:
+
+
| Director Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The external IMDB identifier | String | tt4034228 |
uri | URI mapping to the director | URI | entity://provider/director/kennethlonergan |
value | The name of the director | String | Kenneth Lonergan |
Episode
Episode represents the episode number for serial content like TV Shows; for example, the eighth episode of “Transparent” would have episode number 8.
+
+
| Episode Payload Fields | Description | Type | Example |
|---|---|---|---|
value | The episode number | Integer | 8 |
Event
AnEvent is a reference to a type of event; examples would include sports, music, or other types of events. For example, searching for “Football games” would search for a game event entity and a football sport entity.
+
+
| Event Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The IMDB identifier for the event. | String | tt4034228 |
uri | URI mapping to the event | URI | entity://amazon/events/games |
value | The name of the event type | String | Games |
Franchise
AFranchise is a video entity which can represent a number of video entities, like movies or TV shows. For example, take the fictional franchise “Intergalactic Wars” which represents a collection of movie trilogies, as well as animated and live action TV shows. This entity type was introduced to account for requests by customers such as “Find Intergalactic Wars movies”, which would search for all “Intergalactic Wars” programs of the MOVIE value for MediaType, rather than attempting to match to a single title.
+
+
| Franchise Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The external IMDB identifier | String | tt4034228 |
uri | URI mapping to the franchise | URI mapping to the event | entity://amazon/franchise/intergalacticwars |
value | The name of the genre | String | Intergalactic Wars |
Genre
Genre represents the genre of video media content such as action, drama or comedy. For example, the Action genre might contain the following:
+
+
| Genre Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The external IMDB identifier | String | tt4034228 |
uri | URI mapping to the genre | URI | entity://provider/genre/action |
value | The name of the genre | String | Action |
League
League represents the categorical information for a sporting league; for example, NCAA is a league that might contain the following:
+
+
| League Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The IMDB identifier for the league | String | tt4034228 |
uri | URI mapping to the league | URI | entity://amazon/league/ncaa |
value | The name of the league | String | NCAA |
MediaType
MediaType represents the media type category of a particular piece of content; for example, the MediaType for “Manchester by the Sea” would be MOVIE.
+
+
| MediaType Payload Fields | Description | Type | Example |
|---|---|---|---|
value | The media type; possible values are MOVIE, VIDEO, TV_SHOW | Enum | MOVIE |
ProductionCompany
ProductionCompany represents the production company name for the video media content; for example, Marvels, Disney.
+
+
| ProductionCompany Payload Fields | Description | Type | Example |
|---|---|---|---|
value | Production company name | String | Marvel |
Season
Season represents the season number for serial content like TV Shows; for example, the season two of “Transparent” would have season number 2.
+
+
| Season Payload Fields | Description | Type | Example |
|---|---|---|---|
value | The season number | Integer | 2 |
Sport
Sport represents the categorical information of a sport; for example, football is a sport that might contain the following:
+
+
| Sport Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The IMDB identifier for the sport | String | tt4034228 |
uri | URI mapping to the sports | URI | entity://amazon/sport/football |
value | The name of the sport | String | Football |
SportsTeam
SportsTeam represents the categorical information of a professional sports team; for example, “University of Washington Huskies” is a sports team that might contain the following:
+
+
| SportsTeam Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
└─ imdb | The IMDB identifier for this team. | String | tt4034228 |
uri | URI mapping to the sports team | URI | entity://amazon/sportsteam/huskies |
value | The name of the sports team | String | University of Washington Huskies |
Video
Video represents the identifying data for the piece of video content; for example, “Manchester by the Sea” might contain the following:
+
+
| Video Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | A map of external identifiers for this entity. Key is the provider, value is the id. | Object | — |
ASIN | The external ASIN of this entity | String | B01LTHZVKG |
└─ imdb | The IMDB identifier | String | tt4034228 |
userConfirmations | Object containing information about user confirmations for the item | Object | |
└─ entitlementVoiceActivation | Flag to inform partner if voice enablement of viewing period or entitlement is successful. Possible values - CONFIRMED (optional). | Enum; Default policy - unrecognized values are ignored | CONFIRMED |
uri | URI mapping to the video | URI | entity://provider/movie/manchesterbythesea |
value | The name of the video | String | Manchester by the Sea |
Popularity
Popularity indicates whether the user asks for popular content.
+
+
| Popularity Payload Fields | Description | Type | Example |
|---|---|---|---|
value | Indicates to provider that the user searches for popular content | String | TRUE |
Recency
The resolved values forRecency indicate whether the user asks for new or old content.
+
+
| Recency Payload Fields | Description | Type | Example |
|---|---|---|---|
value | Indicates whether the user searches for new or old content; possible values are NEW, OLD | Enum | NEW |
VideoResolution
VideoResolution represents the requested video resolution in one of the following standards:
- SD (480p)
- HD (720p-1080p)
- 4k (2160p)
- 8k (4320p)
+
+
| VideoResolution Payload Fields | Description | Type | Example |
|---|---|---|---|
value | Video resolution; possible values are SD, HD, 4k, 8k | Enum | HD |
Experience Types
Use theexperience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote.
The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.
-
VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote. -
DEFAULT: The default displays of all search results list format, regardless of the device used for the search.
DEFAULT instead of failing if you receive an unknown value in mode.
Response Example
After receiving aGetDisplayableItems directive, your Lambda should send a GetDisplayableItemsResponse. The response should contain list of id values of the items to display on the device.
The following is an example of a GetDisplayableItemsResponse that your Lambda should send back to Alexa.
Payload Descriptions
The following table describes thepayload fields in your GetDisplayableItemsResponse.
| Field | Description | Data Type |
|---|---|---|
nextTokenoptional | Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests. | String |
mediaItemsrequired | A list of mediaIdentifiers for the videos that are shown as search results on the screen. | List |
mediaIdentifierrequired | Identifier for the mediaItem. See Retrieve Image Size Data from the mediaIdentifier Object. | Object |
idrequired | 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. | String |
Declaring Capability Support for this Interface
To indicate that your video skill supports theAlexa.RemoteVideoPlayer interface, you must indicate support for it in your response to the Discover directive sent through the Alexa.Discovery interface. More details are provided in Alexa.Discovery.
