Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
When users say utterances to find media, such as “Search for [X],” the 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 a SearchAndDisplayResults 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 example SearchAndDisplayResults directive. This is a directive Alexa might send in response to a user’s request to search for “Alexa, show me UW Husky games.”
payload contains the following:

Payload Definitions

The following fields are supported.
FieldDescriptionData Type
entities
optional
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
experience
optional
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
searchText
optional
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
transcribed
optional
Provides the transcribed version of the user’s utterance. See The searchText Object for details.Examples: h.d. popular comedy tv showsString
timeWindow
optional
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.
end
optional
The end time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00ZA string in ISO 8601 format.
start
optional
The start time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00ZA string in ISO 8601 format.

Entity Types

The entities 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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ ASINThe external ASIN of this entityStringB01LTHZVKG
└─ imdbThe IMDB identifier for the actor.Stringtt4034228
uriURI mapping to the actor/actressURIentity://provider/actor/caseyaffleck
valueThe name of the actorStringCasey 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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
entityMetadataA map of meta data associated with the channelObject—
└─ channelNumberThe channel numberInteger1234
└─ channelCallSignThe call sign for the channelStringKBTC
uriThe URI of the channelURIentity://provider/channel/1234
valueThe name of the channelStringPBS

Character

A Character represented in video media content.
Character Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ ASINThe Amazon Standard Identification Number (ASIN) for this entityStringB00DT55P3K
└─ imdbThe IMDB identifier for the character.Stringcharacter id
uriURI mapping to the characterURIentity://provider/character/snowwhite
valueThe name of the characterStringSnow White

Director

Director represents the director name for the video media content; for example, “Kenneth Lonergan” might contain the following:
Director Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
uriURI mapping to the directorURIentity://provider/director/kennethlonergan
valueThe name of the directorStringKenneth 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 FieldsDescriptionTypeExample
valueThe episode numberInteger8

Event

An Event 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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for the event.Stringtt4034228
uriURI mapping to the eventURIentity://amazon/events/games
valueThe name of the event typeStringGames

Franchise

A Franchise 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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
uriURI mapping to the franchiseURI mapping to the evententity://amazon/franchise/intergalacticwars
valueThe name of the genreStringIntergalactic 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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe external IMDB identifierStringtt4034228
uriURI mapping to the genreURIentity://provider/genre/action
valueThe name of the genreStringAction

League

League represents the categorical information for a sporting league; for example, NCAA is a league that might contain the following:
League Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for the leagueStringtt4034228
uriURI mapping to the leagueURIentity://amazon/league/ncaa
valueThe name of the leagueStringNCAA

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 FieldsDescriptionTypeExample
valueThe media type; possible values are MOVIE, VIDEO, TV_SHOWEnumMOVIE

ProductionCompany

ProductionCompany represents the production company name for the video media content; for example, Marvels, Disney.
ProductionCompany Payload FieldsDescriptionTypeExample
valueProduction company nameStringMarvel

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 FieldsDescriptionTypeExample
valueThe season numberInteger2

Sport

Sport represents the categorical information of a sport; for example, football is a sport that might contain the following:
Sport Payload FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for the sportStringtt4034228
uriURI mapping to the sportsURIentity://amazon/sport/football
valueThe name of the sportStringFootball

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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
└─ imdbThe IMDB identifier for this team.Stringtt4034228
uriURI mapping to the sports teamURIentity://amazon/sportsteam/huskies
valueThe name of the sports teamStringUniversity 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 FieldsDescriptionTypeExample
externalIdsA map of external identifiers for this entity. Key is the provider, value is the id.Object—
ASINThe external ASIN of this entityStringB01LTHZVKG
└─ imdbThe IMDB identifierStringtt4034228
userConfirmationsObject containing information about user confirmations for the itemObject
└─ entitlementVoiceActivationFlag to inform partner if voice enablement of viewing period or entitlement is successful. Possible values - CONFIRMED (optional).Enum; Default policy - unrecognized values are ignoredCONFIRMED
uriURI mapping to the videoURIentity://provider/movie/manchesterbythesea
valueThe name of the videoStringManchester by the Sea

Popularity

Popularity indicates whether the user asks for popular content.
Popularity Payload FieldsDescriptionTypeExample
valueIndicates to provider that the user searches for popular contentStringTRUE
Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json “entities”: [..{ “value”: “TRUE”, “type”: “Popularity” } ..], ```

Recency

The resolved values for Recency indicate whether the user asks for new or old content.
Recency Payload FieldsDescriptionTypeExample
valueIndicates whether the user searches for new or old content; possible values are NEW, OLDEnumNEW
Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json “entities”: [..{ “value”: “NEW”, “type”: “Recency” } ..], ```

VideoResolution

VideoResolution represents the requested video resolution in one of the following standards:
  • SD (480p)
  • HD (720p-1080p)
  • 4k (2160p)
  • 8k (4320p)
VideoResolution Payload FieldsDescriptionTypeExample
valueVideo resolution; possible values are SD, HD, 4k, 8kEnumHD
Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json “entities”: [..{ “value”: “4k”, “type”: “VideoResolution” } ..], ```

Experience Types

Use the experience 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.
To ensure forward compatibility, fallback to 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 in SearchAndPlay 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 in SearchAndPlay directives but show the user search results instead of going into playback.

Search by Franchise

Use the same logic as Watch by Franchise in SearchAndPlay 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 in SearchAndPlay directives but show the user search results instead of going into playback.

Handling Ambiguous Requests

Use the same logic as Handling Ambiguous Play Requests in SearchAndPlay 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 the searchText object.

Response Example

If your app handled the directive successfully, your BroadcastReceiver class should send a success intent back with a success status, like this:
For more details, see Step 7: Add a Broadcast Receiver. Also see the AlexaDirectiveReceiver class in the sample app for a more specific code example.

Declaring Capability Support for this Interface

To receive 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:
Last modified on June 9, 2021