Entity Types for Video Content

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. Possible values for type are:

MediaType

MediaType represents the media type category of a particular piece of content; for example, "Manchester by the Sea" would be MediaType MOVIE.

Field Description Type Example
value The media type; possible values - MOVIE, VIDEO, TV_SHOW Enum MOVIE

Actor

Actor represents an actor credited in video media content; for example, Gaby Hoffman might contain the following:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for the actor. String ST0000000666661
value The name of the actor String Gaby Hoffman

App

App represents an application; for example, Prime Video might contain the following:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
ENTITY_ID The identifier for the application. The Id is fetched from the Application list. String amzn1.alexa-ask-target.app.72095
value The name of the application String Prime Video

Channel

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

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for the character. String ST0000000123456
entityMetadata A map of metadata 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. String entity://provider/channel/1234
value The name of the channel. String PBS

Character

A character represented in video media content; for example, Snow White might contain the following:

Field Description Type Example
externalIds A key/value 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
gracenote The Gracenote identifier for the character. String ST0000000123456
value The name of the character String Snow White

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.

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for the event. String 100
value The name of the event type String Games

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 MediaType, rather than attempting to match to a single title.

Field Description Type Example
value The name of the franchise 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:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for the genre. String 101
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:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for the league. String L0000000666661
value The name of the league String NCAA

Popularity

Popularity indicates whether the user asks for popular content.

Field Description Type Example
value Indicates to provider that the user searches for popular content String TRUE

ProductionCompany

ProductionCompany represents the production company name for the video media content; for example, "Marvel" or "Disney."

Field Description Type Example
value Production company name String Marvel

ProgramHierarchy

ProgramHierarchy represents the level in the program information hierarchy for serial content like TV shows. For example, a request to display the seasons of "Bosch" would include a ProgramHierarchy value of "Seasons".

Field Description Type Example
value The program information hierarchy level; possible values - Episodes, Seasons Enum Seasons

Recency

The resolved values for Recency indicate whether the user asks for new or old content.

Field Description Type Example
value Indicates whether the user searches for new or old content; possible values: NEW, OLD Enum NEW

Season and Episode

Season and Episode represents the season and episode numbers for serial content like TV Shows; for example, the eighth episode in season two of "Transparent" would have season number 2, episode number 8.

Field Description Type Example
type The season number Integer 2
value The episode number Integer 8

Sport

Sport represents the categorical information of a sport; for example, football is a sport that might contain the following:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for the sport String SP0000000666661
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:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
gracenote The Gracenote identifier for this team. String 100
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:

Field Description Type Example
externalIds A key/value map of external identifiers for this entity. Key is the provider, value is the Id. Object  
asin The Amazon Standard Identification Number (ASIN) of the video String B01M3X9T06
gracenote The Gracenote identifier String MV0000000666661
value The name of the video String Manchester by the Sea

VideoResolution

VideoResolution represents the requested video resolution in one of the following standards:

  • SD (480p)
  • HD (720p-1080p)
  • 4k (2160p)
  • 8k (4320p)
Field Description Type Example
value Video resolution; possible values: SD, HD, 4k, 8k Enum HD

Example: SearchAndPlay with Entities Specified

{
  "directive": {
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "header": {
      "messageId": "5f2477e6-8f57-4606-af18-6990b8646794",
      "name": "SearchAndPlay",
      "namespace": "Alexa.RemoteVideoPlayer",
      "payloadVersion": "3"
    },
    "payload": {
      "entities": [{
        "externalIds": {
          "gracenote": "MV000000099001"
        },
        "name": "Manchester by the Sea",
        "type": "Video"
      }],
      "timeWindow": {
        "end": "2016-09-07T23:59:00+00:00",
        "start": "2016-09-01T00:00:00+00:00"
      }
    }
  }
}