Entity Type Reference

Note: Sign in to the developer console to build or publish your skill.

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.

Important: The Gracenote catalog is deprecated.

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

Last updated: Oct 10, 2022

Entity Type Reference

Entity types overview

Actor

App

Channel

Character

Director

Episode

Event

Franchise

Genre

League

MediaType

Popularity

ProductionCompany

Recency

Season

Sport

SportsTeam

Video

VideoResolution

Related topics