Entity Type 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, IMDb is the provider of video content identifiers in the IMDb database.

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

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": {
            "imdb": "nm0000020"
        },
        "type": "Actor",
        "value": "Actor Name",
        "uri": "entity://provider/actor/amzn1.alexa-vsk.actor.9a0af8d4b61d178a49f7eeed68fba368"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Actor.

String

Yes

value

Name of the actor.

String

Yes

uri

Mapping to the actor entity.

String

Yes

App

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

{
    "entities": [{
        "externalIds": {
            "imdb": "co0051941"
        },
        "type": "App",
        "value": "Prime Video"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to App.

String

Yes

value

Name of the app.

String

Yes

Channel

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

{
    "entities": [{
        "externalIds": {
            "key name": "channel external id"
        },
        "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 Required

externalIds

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

Object

Yes

entityMetadata

Information associated with the channel.

Object

Yes

entityMetadata.channelNumber

Channel number.

Integer

Yes

entityMetadata.channelCallSign

Call sign for the channel.

String

Yes

type

Name of the entity type. Set to Channel.

String

Yes

value

Name of the channel.

String

Yes

uri

URI of the channel.

String

Yes

Character

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

{
    "entities": [{
        "externalIds": {
            "ASIN": "B00DT55P3K",
            "imdb": "character id"
        },
        "type": "Character",
        "value": "Snow White"
    }]
}

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

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Character.

String

Yes

value

Name of the character.

String

Yes

Director

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

{
    "entities": [{
        "externalIds": {
            "imdb": "nm0741627"
        },
        "type": "Director",
        "value": "Directors name"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Director.

String

Yes

value

Name of the director.

String

Yes

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 Required

type

Name of the entity type. Set to Episode.

String

Yes

value

Episode number.

String

Yes

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": {
            "key name": "event external id"
        },
        "type": "Event",
        "value": "Games"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Event.

String

Yes

value

Name of the event category.

String

Yes

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 Required

type

Name of the entity type. Set to Franchise.

String

Yes

value

Name of the franchise.

String

Yes

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": {
            "key name": "genre external id"
        },
        "type": "Genre",
        "value": "Action"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Genre.

String

Yes

value

Name of the genre.

String

Yes

League

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

{
    "entities": [{
        "externalIds": {
            "key name": "league id"
        },
        "type": "League",
        "value": "NCAA"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to League.

String

Yes

value

Name of the sporting league.

String

Yes

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 Required

type

Name of the entity type. Set to MediaType.

String

Yes

value

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

String

Yes

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 Required

type

Name of the entity type. Set to Popularity.

String

Yes

value

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

String

Yes

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 Required

type

Name of the entity type. Set to ProductionCompany.

String

Yes

value

Name of the production company.

String

Yes

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 Required

type

Name of the entity type. Set to Recency.

String

Yes

value

Content age.
Valid values: NEW, OLD.

String

Yes

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 Required

type

Name of the entity type. Set to Season.

String

Yes

value

Season number.

String

Yes

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": {
            "key name": "sport id"
        },
        "type": "Sport",
        "value": "Football"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Sport.

String

Yes

value

Name of the sport.

String

Yes

SportsTeam

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

{
    "entities": [{
        "externalIds": {
            "key name": "sports team id"
        },
        "type": "SportsTeam",
        "value": "University of Washington Huskies"
    }]
}

The following table shows the definition of the entity type.

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to SportsTeam.

String

Yes

value

Name of the sports team.

String

Yes

Video

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

{
    "entities": [{
        "externalIds": {
            "imdb": "tt0050083",
            "asin": "B000056HEC"
        },
        "type": "Video",
        "value": "Manchester by the Sea"
    }]
}

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

Property Description Type Required

externalIds

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

Object

Yes

type

Name of the entity type. Set to Video.

String

Yes

value

Name of the video content.

String

Yes

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 Required

type

Name of the entity type. Set to VideoResolution.

String

Yes

value

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

String

Yes