Entity Types Reference

Users can ask Alexa to search for video content by specifying characteristics of the content, such as a season and episode of a TV show, or a genre of movie. Alexa sends these characteristics, called entity types, to your skill in the entities array. This reference defines the entity types that Alexa might send to your skill.

Some entity types include external identifiers that provide additional information about the entity. The external identifier is a key-value map where the key defines the provider of the identifier. For example, Gracenote is the provider of video content identifiers in the Gracenote IDs database and Amazon Standard Identification Number (ASIN) is the video content product identifier within Amazon.

Entity types overview

The following table shows the entity types that Alexa supports.

Entity type Description

Actor

An actor credited in video media content.

App

An application that the user might launch, such as Prime Video.

Channel

Represents the identifying data for a television channel, such as PBS.

Character

A character in a movie or TV show, such as Snow White.

Director

A director credited in video media content.

Episode

Episode number for serial content.

Event

A type of event, such as a music concert or sporting event.

Franchise

Related video entities, such as a trilogy or five part series.

Genre

Category of video content, such as action, drama, or comedy.

League

Represents the name of a sporting league, such as NCAA.

MediaType

Type category of the video content, such as movie or TV show.

Popularity

Indicates whether the user asks for popular content.

ProductionCompany

Production company name for the video media content, such as Disney.

ProgramHierarchy

Represents the level in the information hierarchy for serial content, such as seasons and episodes.

Recency

Indicates whether the user asks for new or old content.

Season

Season number for serial content.

Sport

Category of a sport, such as football.

SportsTeam

Name of a professional sports team, such as University of Washington Huskies.

Video

Identifying data for the piece of video content, such as the movie title.

VideoResolution

Represents the requested video resolution, such as HD.

Actor

This entity type represents an actor credited in video media content. The following example shows an Actor entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "P000000099001"
        },
        "type": "Actor",
        "value": "Actor Name"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the actor.

String

type

Name of the entity type. Set to Actor.

String

value

Name of the actor.

String

App

This entity type represents an application that the user requested. The following example shows an App entity type.

{
    "entities": [{
        "externalIds": {
            "ENTITY_ID": "amzn1.alexa-ask-target.app.72095"
        },
        "type": "App",
        "value": "Prime Video"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.ENTITY_ID

The application identifier.
For Amazon predefined identifiers, see Application list.

String

type

Name of the entity type. Set to App.

String

value

Name of the app.

String

Channel

This entity type represents the identifying data for a television channel. The following example shows a Channel entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "TV000000000001"
        },
        "entityMetadata": {
            "channelNumber": 15,
            "channelCallSign": "KBTC"
        },
        "type": "Channel",
        "value": "PBS",
        "uri": "entity://provider/channel/15"
    }]
}

The following table shows the definition of the entity type..

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the channel.

String

entityMetadata

Information associated with the channel.

Object

entityMetadata.channelNumber

Channel number.

Integer

entityMetadata.channelCallSign

Call sign for the channel.

String

type

Name of the entity type. Set to Channel.

String

value

Name of the channel.

String

uri

URI of the channel.

String

Character

This entity type represents a character in video media content. The following example shows a Character entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "ST0000000123456",
            "ASIN": "B00DT55P3K"
        },
        "type": "Character",
        "value": "Snow White"
    }]
}

The following table shows the definition of the entity type..

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the character.

String

externalIds.ASIN

ASIN for the character. For this entity type, the key is upper case.

String

type

Name of the entity type. Set to Character.

String

value

Name of the character.

String

Director

This entity type represents the director of video media content. The following example shows a Director entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "gracenote ID"
        },
        "type": "Director",
        "value": "Kenneth Lonergan"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the director.

String

type

Name of the entity type. Set to Director.

String

value

Name of the director.

String

Episode

This entity type represents the episode number for serial content, such as the eighth episode in season two. The following example shows an Episode entity type.

{
    "entities": [{
        "type": "Episode",
        "value": 8
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to Episode.

String

value

Episode number.

Integer

Event

This entity type represents a type of event, such as a sporting or music event. For example, a search for a football game uses the Event entity type for game and the Sport entity type for football. The following example shows an Event entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "SP0000000666661"
        },
        "type": "Event",
        "value": "Games"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the event.

String

type

Name of the entity type. Set to Event.

String

value

Name of the event category.

String

Franchise

This entity type represents related video entities, such as movies and TV shows. For example, take the fictional franchise, Intergalactic Wars. This franchise might represent a collection of movie trilogies and animated TV shows. With this entity type, customers can say, "Alexa, find Intergalactic Wars". Instead of a single title, the search result includes all movies and TV shows from the franchise.

The following example shows a Franchise entity type.

{
    "entities": [{
        "type": "Franchise",
        "value": "Intergalactic Wars"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to Franchise.

String

value

Name of the franchise.

String

Genre

This entity type represents the category of video media content, such as action, drama, or comedy. The following example shows a Genre entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "gracenote ID"
        },
        "type": "Genre",
        "value": "Action"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the genre.

String

type

Name of the entity type. Set to Genre.

String

value

Name of the genre.

String

League

This entity type represents the sporting league name, such as NCAA. The following example shows a League entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "gracenote ID"
        },
        "type": "League",
        "value": "NCAA"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the sporting league.

String

type

Name of the entity type. Set to League.

String

value

Name of the sporting league.

String

MediaType

This entity type represents the media category of the video content, such as Movie or TV show. The following example shows a MediaType entity type.

{
    "entities": [{        
        "type": "MediaType",
        "value": "MOVIE"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to MediaType.

String

value

Name of the media category.
Valid values: MOVIE, VIDEO, TV_SHOW.

String

Popularity

This entity type indicates whether the user asks for popular content. The following example shows a Popularity entity type.

{
    "entities": [{
        "type": "Popularity",
        "value": "TRUE"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to Popularity.

String

value

Indicates whether the user requested popular content.
Valid values: TRUE, FALSE.

String

ProductionCompany

This entity type represents the production company name for the video media content. The following example shows a ProductionCompany entity type.

{
    "entities": [{
        "type": "ProductionCompany",
        "value": "Marvel"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to ProductionCompany.

String

value

Name of the production company.

String

ProgramHierarchy

This entity type represents the information hierarchy for serial content, such as seasons and episodes. The following example shows a ProgramHierarchy entity type.

{
    "entities": [{
        "type": "ProgramHierarchy",
        "value": "Seasons"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to ProgramHierarchy.

String

value

Hierarchy designation.
Valid values: Episodes, Seasons.

String

Recency

This entity type indicates the whether the user searches for new or old content. The following example shows a Recency entity type.

{
    "entities": [{
        "type": "Recency",
        "value": "Seasons"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to Recency.

String

value

Content age.
Valid values: NEW, OLD.

String

Season

This entity type represents the season number for serial content, such as season two. The following example shows a Season entity type.

{
    "entities": [{
        "type": "Season",
        "value": 2
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to Season.

String

value

Season number.

Integer

Sport

This entity type represents a category of sports, such as a football or soccer. The following example shows a Sport entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "gracenote ID"
        },
        "type": "Sport",
        "value": "Football"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the sport.

String

type

Name of the entity type. Set to Sport.

String

value

Name of the sport.

String

SportsTeam

This entity type represents a sports team. The following example shows a SportsTeam entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "gracenote ID"
        },
        "type": "SportsTeam",
        "value": "University of Washington Huskies"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the sport team.

String

type

Name of the entity type. Set to SportsTeam.

String

value

Name of the sports team.

String

Video

This entity type represents video media content. The following example shows a Video entity type.

{
    "entities": [{
        "externalIds": {
            "gracenote": "MV0000000666661",
            "asin": "B01M3X9T06"
        },
        "type": "Video",
        "value": "Manchester by the Sea"
    }]
}

The following table shows the definition of the entity type..

Property Description Type

externalIds

A key-value map of external identifiers for this entity.

Object

externalIds.gracenote

Gracenote ID for the video content.

String

externalIds.asin

ASIN of the video content. For this entity type, the key is lower case.

String

type

Name of the entity type. Set to Video.

String

value

Name of the video content.

String

VideoResolution

This entity type represents the requested video resolution. You can specify the following standard resolutions:

  • Standard Definition (SD), 480p
  • High Definition (HD), 720p – 1080p
  • Ultra high definition 4K, 2160p
  • Ultra high definition 8K, 4320p

The following example shows a VideoResolution entity type.

{
    "entities": [{
        "type": "VideoResolution",
        "value": "HD"
    }]
}

The following table shows the definition of the entity type.

Property Description Type

type

Name of the entity type. Set to VideoResolution.

String

value

Video resolution.
Valid values: SD, HD, 4k, 8k.

String