アクセスいただきありがとうございます。こちらのページは現在英語のみのご用意となっております。順次日本語化を進めてまいりますので、ご理解のほどよろしくお願いいたします。

GetDisplayableItems Directives (VSK MM)

When users make utterances to find content or try to access the content provider landing page, the VideoContentProvider API sends a GetDisplayableItems directive to your Lambda.

The following diagram shows the expected Alexa directive and Lambda response;

GetDisplayableItems Directive and Lambda GetDisplayableItemsResponse

Utterances for GetDisplayableItems

Alexa sends a GetDisplayableItems directive to your Lambda when users say the following utterances.

Feature Sample Utterances Expected Response
Search for <title>

Search for Breaking Bad

Find The Big Bang Theory

Suche nach <title>

Nach <title> suchen

<Breaking Bad>

Cherche Breaking Bad

Trouve Breaking Bad

Trouve-moi Breaking Bad

Cherche/trouve breaking bad

cerca breaking bad

<House, The Office, Sneaky Pete>

busca breaking bad

busca breaking bad

búscame breaking bad

búsca me breaking bad

{title} 探して

{title} を検索して

A list of matches for the title is presented to the user.

Search by Media Type

Search movies

Suche nach <type>

<filme, videos, film>

Cherche des films

Trouve des films

Trouve-moi des films

Cherche/trouve des films

cerca dei film

busca películas

busca películas

busca pelís

búscame películas

búscame pelís

búsca me películas

búsca me pelís

{media type} 探して

{media type} を検索して

A list of matches for the desired media type is presented to the user.

Search by Actor

Search for sean connery

Search for movies with Tom Hanks.

Suche nach <actor>

<Ann Blyth, Axel Deller, John Oliver>

Cherche Sean Connery

Cherche/trouve sean connery

cerca sean connery

<Gianni Franco, Sonia Scotti, Stefano Sani>

busca sean connery

busca sean connery

busca a sean connery

búscale a sean connery

búsca le a sean connery

{actor} 探して

{actor} を検索して

{actor}の{media type} を探して

{actor}の{media type} を検索して

{actor}が出てる{media type} 探して

{actor}が出てる{media type} を検索して

*{media type}:映画/ドラマ/やつ/もの/の

A list of matches featuring the actor is presented to the user.

Search <title> with season number

Search breaking bad season two

Suche nach <title> Staffel <number>

Suche nach der <number>. Staffel von <title> <Breaking Bad>

Cherche la saison 2 de Breaking Bad

Cherche la deuxième saison de Breaking Bad

Trouve la saison 2 de Breaking Bad

Trouve la deuxième saison de Breaking Bad

Trouve-moi la saison 2 de Breaking Bad

Trouve-moi la deuxième saison de Breaking Bad

Cherche/trouve la deuxième saison/saison 2 de breaking bad

cerca la seconda stagione di breaking bad

cerca la stagione due di breaking bad

<House, The Office, Sneaky Pete>

busca la temporada 2 de breaking bad

busca la segunda temporada de breaking bad

busca la temporada 2 de breaking bad

busca la segunda temporada de breaking bad

búscame la temporada 2 de breaking bad

búscame la segunda temporada de breaking bad

búsca me la temporada 2 de breaking bad

búsca me la segunda temporada de breaking bad

{title} シーズン{season number} 探して

{title} シーズン{season number} を探して

{title} シーズン{season number} を検索して

All episodes for the matching season are presented to the user.

Search <title> with episode number

Search for breaking bad episode five

Suche nach <title> Folge <number>

Suche nach <title> Episode <number>

Suche nach der <number>. Folge von <title>

Suche nach der <Number>. Episode von <title>

<Breaking Bad>

Cherche l'épisode 5 de Breaking Bad

Cherche le cinquième épisode de Breaking Bad

Cherche/trouve le/la cinquième épisode/épisode 5 de breaking bad

cerca il quinto episodio di breaking bad

cerca l'episodio cinque di breaking bad

<House, The Office, Sneaky Pete>

busca el episodio 5 de breaking bad

busca el capítulo 5 de breaking bad

busca el episodio 5 de breaking bad

busca el capítulo 5 de breaking bad

búscame el episodio 5 de breaking bad

búscame el capítulo 5 de breaking bad

búsca me el episodio 5 de breaking bad

búsca me el capítulo 5 de breaking bad

{title} エピソード{episode number} 探して

{title} エピソード{episode number} を探して

{title} エピソード{episode number} を検索して

A list of available episodes within the season the user recently watched appears. For example, if the user's viewing progress is within Season 2, a list of episodes from Season 2 appears.

Search <title> with season and episode number

Search for breaking bad season two episode five

Find 'The Big Bang Theory' Season 1 episode 4.

Suche nach <title> Staffel <season number> Folge <episode number>

Suche nach <title> Staffel <season number> Episode <episode number>

Suche nach der <episode number>. Folge von <title> in Staffel <season number>

Suche nach der <episode number>. Episode von <title> in Staffel <season number>

<Breaking Bad>

Cherche l'épisode 5 de la saison 2 de Breaking Bad

Cheche l'épisode 5 de la deuxième saison de Breaking Bad

Cherche le cinquième épisode de la saison 2 de Breaking Bad

Cherche l'épisode 5 de la deuxième saison de Breaking Bad

Cherche/trouve le/la cinquième épisode/épisode 5 de la deuxième saison/saison 2 de breaking bad

cerca il quinto episodio della stagione due di breaking bad

cerca l'episodio cinque della stagione due di breaking bad

<House, The Office, Sneaky Pete>

busca el episodio 5 de la temporada 2 de breaking bad

busca el episodio 5 de la segunda temporada de breaking bad

busca el episodio 5 de la temporada 2 de breaking bad

busca el episodio 5 de la segunda temporada de breaking bad

búscame el episodio 5 de la temporada 2 de breaking bad

búscame el episodio 5 de la segunda temporada de breaking bad

búsca me el episodio 5 de la temporada 2 de breaking bad

búsca me el episodio 5 de la segunda temporada de breaking bad

{title} シーズン{season number} エピソード{episode number} 探して

{title} シーズン{season number} エピソード{episode number} を探して

{title} シーズン{season number} エピソード{episode number} を検索して

A list of available episodes for the season the user requested appears, including the episode the user specifically asked for.

Search by franchise <title>

Search for star trek

Suche nach <title>

Zeige mir <title>

<Star Wars, James Bond, Batman, Star Trek>

Cherche Star Trek

Trouve Star Trek

Cherche/trouve star treck

cerca star trek

<Superman, cars, Scream>

busca star trek

busca star trek

búscame star trek

búsca me star trek

{franchise} 探して

{franchise} を探して

{franchise} を検索して

The user is presented with a list of matching results for the franchise.

Search by Character Name

Search for james bond

Suche nach <actor>

Suche nach einem Film mit <actor>

<James Bond>

Cherche James Bond

Trouve James Bond

Cherche/trouve james bond

cerca james bond

<Superman>

busca james bond

busca james bond

busca a james bond

busca james bond

búscame james bond

búsca me james bond

{character} 探して

{character} を探して

{character} を検索して

{character}の{media type} 探して

{character}の{media type} を探して

{character}の{media type} を検索して

{character}が出てる{media type} 探して

{character}が出てる{media type} を探して

{character}が出てる{media type} を検索して

*{media type}:映画/ドラマ/やつ/もの/の

The user is presented with a list of matching results for media featuring the character name.

Search by director name

Search for quentin tarantino

Suche nach einem Film von <director>

Suche nach <director>

Cherche Quentin Tarantino

Trouve Quentin Tarantino

Cherche/trouve xavier dolan

cerca quentin tarantino

busca quentin tarantino

busca quentin tarantino

busca a quentin tarantino

búscame quentin tarantino

búscame a quentin tarantino

búsca me quentin tarantino

búsca me a quentin tarantino

{director name}監督の{media type}探して

{director name}監督の{media type}を探して

{director name}監督の{media type}を検索して

{director name}が監督してる{media type}探して

{director name}が監督してる{media type}を探して

{director name}が監督してる{media type}を検索して

The user is presented with a list of matching results for media produced by the requested director.

Search by production company

Search for disney

Suche nach Filmen von <name>

Suche nach einem Film von <name>

Cherche Disney

Trouve Disney

Cherche/trouve disney

cerca disney

busca disney

busca disney

búscame disney

búsca me disney

{company} 探して

{company} を探して

{company} を検索して

The user is presented with a list of matching results for media from the production company.

Search by genre name

Search for comedy

Search comedy movies with Tom Hanks.

Suche nach <genre>

Suche eine <genre>

<Familie, Architektur, Landestypisch>

Cherche une comédie

Trouve une comédie

Cherche des comédies

Trouve des comédies

Cherche/trouve des comédies

cerca una commedia

<Commedia>

busca comedia

busca comedia

busca comedias

búscame comedias

búsca me comedias

{genre} 探して

{genre} を探して

{genre} を検索して

The user is presented with a list of matching results for media from the requested genre (personalized through an algorithm that selects recommended media for the user).

Search by sports team

Search seahawks

Suche nach <sports team>

<Erster. FC Heidenheim, Erster FC Heidenheim, Erster FC Kaiserslautern>

Cherche les Bleus

Cherche/trouve le/les Canadiens

cerca juventus

<Aberdeen, ac milan>

busca el Madrid

busca el América

búscame el América

búsca me el América

{sports team} 探して

{sports team} を探して

{sports team} を検索して

The user is presented with a list of matching results for the sports team.

Search by sports type

Search for soccer

Suche nach <sports type>

Cherche du foot/football

Trouve du foot/football

Cherche/trouve du hockey

cerca calcio

busca fútbol

busca fútbol

búscame fútbol

búscame el útbol

busca el fútbol

búsca me fútbol

búsca me el fútbol

{sports type} 探して

{sports type} を探して

{sports type} を検索して

The user is presented with a list of matching results for the sports type (preferably based on recommendations for the user).

Search by sports league

Search for n. b. a. league

Suche nach <sports league>

<Erste Baseball Bundesliga, Zweite Baseball Bundesliga, Zweite Bundesliga>

Cherche la n.b.a.

Trouve la n.b.a.

Cherche/trouve la LNH/NHL/ligue nationale

cerca l'n.b.a.

cerca la n.b.a.

<America's Cup>

busca la n. b. a.

busca la n. b. a.

búscame la n. b. a.

búsca me la n. b. a.

{sports league} 探して

{sports league} を探して

{sports league} を検索して

The user is presented with a list of matching results for the sports league (preferably based on recommendations for the user).

Search by sports event

Search for soccer game

Suche nach <sports event>

Suche <sports event>

Cherche un match de foot/football

Trouve un match de foot/football

Cherche/trouve des matchs/parties/games de hockey

cerca una partita di calcio

cerca partite

<gli europei>

busca partidos de fútbol

busca partidos de fútbol

búscame partidos de fútbol

búsca me partidos de fútbol

{sports event} 探して

{sports event} を探して

{sports event} を検索して

The user is presented with a list of matching results for the sports event (preferably based on recommendations for the user).

Launch <partner> app

Launch Netflix app

Open Amazon video

Starte <partner app>

<partner app> starten

Öffne <partner app>

<partner app> öffnen

<partner app> aufrufen

Ruf <partner app> auf

<youview, netflix, zattoo, hulu>

Lance Netflix

Ouvre Netflix

lance/ouvre/pars Netflix

lance/ouvre/pars l'appli/l'app/l'application (de) Netflix

apri (l'app di) Netflix

avvia Netflix

<Netflix>

abre (la app de) Netflix

abre (la app de) Netflix

{app} 開いて

{app} 見せて

{app} 起動

{app} 起動して

{app} に行って

{app} に戻って

The requested app launches and shows a list of available media to play. Multimodal devices have a homepage template that gets populated with media potentially grouped in different categories.

Launch special character title

Launch a. t. and t. u-verse app

Starte a, t, und t. u-verse

A. t. und t. u.verse starten

Lance a.t. et t. u-verse

Ouvre a.t. et t. u-verse

no translation yet

abre (la app de) Movistar + (plus)

no translation yet

no translation yet

no translation yet

The requested app launches and shows a list of available media to play. Multimodal devices have a homepage template that gets populated with media potentially grouped in different categories.

Launch app

Launch app

App starten

Starte App

App öffnen

Öffne die App

Lance l'application

Ouvre l'application

Lance l'appli

Ouvre l'appli

lance/ouvre/pars l'appli/l'app/l'application

apri (l')app

avvia (l')app

abre (la) app

abre (la) app

アプリを開いて

アプリを起動して

The requested app launches and shows a list of available media to play. Multimodal devices have a homepage template that gets populated with media potentially grouped in different categories.

Handling GetDisplayableItems Directives

When users search for content using criteria like VideoName, 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.

{
   "type": "SORTTYPE",
   "value": "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 a GetDisplayableItems directive:

{
    "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"
            }
        }
    }
}

GetDisplayableItems Example (Landing Page)

When a user opens the provider landing page, Alexa sends two GetDisplayableItems directives.

  • The first directive is to retrieve categories for the landing page by setting the itemType property to CATEGORY and including a sortType of RECOMMENDED.
  • The second directive obtains the featured video for the landing page where the directive sets the itemType to VIDEO instead.

After that, 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.

The following shows an example of a GetDisplayableItems directive used for a landing page:

{
   "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
        }
    }
}

itemType specifies the type of item to be searched. The values can be either VIDEO or CATEGORY.

Payload Descriptions

The following table defines the payload fields for GetDisplayableItems directives.

Payload Descriptions
Field Description Data Type
entities
required

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:

 {
  "type": "Channel",
  "value": "PBS",
  "externalIds": {
      "gracenote": "MV000000099001"
  },
  "entityMetadata": {
      "channelCallSign": "KBTC",
      "channelNumber": "123"
  }
} 

List
type

Entity types for video content. For information about video content entity types, see [Entity Types for Video Content](../video-skills-fire-tv-apps/entity-types-for-video-content.html). In addition to that list, Alexa Skills Kit has added the following types for multimodal devices: LISTTYPE, SORTTYPE.

LISTTYPE is populated when users wants to browse their Watchlist or Library. For example, utterances like "Show me my Watchlist" or "Show me my Video Library." LISTTYPE 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" — used to show videos that are in the users' library. Typically, these are the videos that have been purchased by the user.

SORTTYPE 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. SORTTYPE can have the following enum value:

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

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

String
value
required

The value of the entity. For channels, the name of the channel.

Examples: Interstellar, PBS

String
itemType

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:

  • The first GetDisplayableItems directive is to retrieve categories for the landing page by setting the itemType property to CATEGORY and including a sortType of RECOMMENDED.
  • The second GetDisplayableItems directive obtains the featured video for the landing page where the request sets the itemType to VIDEO instead.

After receiving your response (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
externalIds

A map of external identifiers for this entity; key is the provider, value is the id.

Examples: key = gracenote or gti, value = SH000000012

Object
Gracenote

The external Gracenote identifier.

Example: ST0000000666661

String
contentType
required

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, from your DVR." If the contentType is RECORDING, Alexa renders a prompt such as, "Here's the Academy Awards from your DVR."

Examples: RECORDING, LIVE, ON_DEMAND

Enum
locale
required

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
minResultLimit
required

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
maxResultLimit
required

A limit to the maximum number of results to return. See description of minResultLimit field for more details.

Example: 25

Integer
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 containing start and end times.
end

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

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.

Response Example

After receiving a GetDisplayableItems 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.

{
"directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetDisplayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [{
                    "mediaIdentifier": {
                        "id": "tt1254207"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt0807840"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt7993892"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt4957236"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt2285752"
                    }
                }
            ]
        }
    }
};

Payload Descriptions

The following table describes the payload fields in your GetDisplayableItemsResponse.

Payload Descriptions
Field Description Data Type
nextToken

Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests.

String
mediaItems
required

A list of mediaIdentifiers for the videos that are shown as search results on the screen.

List
mediaIdentifier
required

Identifier for the mediaItem.

Object
id
required

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 the Alexa.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.