Alexa.RemoteVideoPlayer interface sends SearchAndDisplayResults directives to your app or Lambda. For this directive, your app’s logic should take users to search results pages rather than going directly to media playback.
Utterances for SearchAndDisplayResults Directives
Alexa sends aSearchAndDisplayResults directive to your app (for app-only integrations) or to your Lambda (for cloudside integrations) when users say the following utterances.
SearchAndDisplayResults Directive Example
The following is an exampleSearchAndDisplayResults directive. This is a directive Alexa might send in response to a user’s request to search for “Alexa, show me UW Husky games.”
- App-only Integrations
- Cloudside Integrations
payload contains the following:Payload Definitions
| Field | Description | Data Type |
|---|---|---|
entitiesoptional | An array of entity objects to play, such as a Title, Franchise, Actor, Team, or MediaType. See Entity Types for more details about entity types and values. | array |
experienceoptional | An object that optimizes the display of search results. With the experience object, you can change the search results based on the device your customer used to search. See Experience Types for more details about the experience object and its values. | Object containing mode |
searchTextoptional | Contains a transcribed version of the user’s search query as a string value in the transcribed field. See Viewing the Customer’s Actual Request for details. | Object containing transcribe |
transcribedoptional | Provides the transcribed version of the user’s utterance. See The searchText Object for details.Examples: h.d. popular comedy tv shows | String |
timeWindowoptional | Provides the time window for the content the customer wants to play. For example if a customer wants to play an episode from last week, time window would indicate the preceding week. | Object containing start and end times. |
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. |
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. |
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.
Handling SearchAndDisplayResults Directives
SearchAndDisplayResults directives contain instructions to search for media and then display the results of a search in a way that is appropriate for your application. The SearchAndDisplayResults directive contains an array of entities that specifies what to search for.
(The SearchAndDisplayResults directive is similar to GetDisplayableItems in the video skills for multimodal implementations.)
The following sections provide guidance for handling SearchAndDisplayResults directives for different types of requests.
Search by Title
Use the same logic as Watch by Title inSearchAndPlay directives but show the user search results instead of going into playback.
Search by Title, Episode, and Season
Use the same logic as Watch by Title, Episode, and Season inSearchAndPlay directives but show the user search results instead of going into playback.
Search by Franchise
Use the same logic as Watch by Franchise inSearchAndPlay directives but show the user search results instead of going into playback.
Search by Genre, Sport, Team, League, and Other Ambiguous Search Directives
Use the same logic as Watch by Genre, Sport, Team, League, and Other Ambiguous Play Directives inSearchAndPlay directives but show the user search results instead of going into playback.
Handling Ambiguous Requests
Use the same logic as Handling Ambiguous Play Requests inSearchAndPlay directives but show the user search results instead of going into playback.
Artwork
In your list of results that you present to the user, include relevant artwork applicable to the titles. The artwork should make it easier for the user to identify the content you are recommending in the search.Viewing the Customer’s Actual Request
See Viewing the Customer’s Actual Request for instructions and recommendations related to thesearchText object.
Response Example
- App-only Integrations
- Cloudside Integrations
AlexaDirectiveReceiver class in the sample app for a more specific code example.Declaring Capability Support for this Interface
- App-only Integrations
- Cloudside Integrations
SearchAndDisplay directives to your app from the RemoteVideoPlayer interface, you must indicate support for this interface when you declare your capabilities. See the following for more information on declaring capabilities with app-only integrations:
