TV and Movies

Mark up your TV and Movie content to make Google Search an entry point for discovering and consuming TV shows and movies.

Watch actions

When a user searches for the name of a show or movie on Google or on their mobile device, a Knowledge Graph card can appear prominently in the Search results with watch actions that enable users to watch TV shows and movies from streaming services. Watch actions in the card will use links to partner apps or web landing pages, bringing users directly from the Knowledge Graph card to the specific episode or movie.

Movie lists

When a user searches for best action films or provides similar list-seeking queries, your marked up movie content can appear as a host-specific carousel in Search Results. To enable host-specific lists for movies, provide both ItemList markup and individual movie item markup. In addition to individual movie pages that the list page points to, your site must also provide user-facing content that lists the movies, since this page will be a destination for one of the carousel links from Search. For implementation details, see Mark up host-specific lists.

Examples

Movie Example

TVEpisode Example

TVSeason Example

TVSeries Example

Guidelines for Watch Actions

For a streamlined user experience, links to your content should support autoplay. On clicking a watch action link, your content should immediately start playing rather than directing the user to a landing page which requires subsequent clicks to initiate playback.

In addition to TV episode markup, you can also markup TV seasons and TV series in the following way:

  • You have a distinct landing page for the TV season or series, separate from the episode landing pages, and the user can either view information about the season/series, or watch the season or series.
    • To send users to an information page, use a view action.
    • To send users directly to the content so they can watch it, use a watch action.
    • If users can go to either a landing page for information about the season or series or stream the content for the season or series, you can provide both a view action and a watch action.
    • If you provide a watch action for a season or series, it should take users to the last place they left off in the season or series. If they haven't previously viewed the content, the watch action should take them to the beginning of the series or season.
  • You have different watch action offers for users if they rent or purchase the entire TV season or series at once. Example: purchasing the 16-episode second season of The Walking Dead may cost $28 as opposed to purchasing individual episodes for $1.99 each.

Type definitions

Common properties

The following properties should be defined for every Movie and TVEpisode item.

Properties
@id

URL, recommended

Globally unique ID of the work in the form of a URL. The ID should be stable and not change over time. The URL is treated as an opaque string and does not have to be a working link.

actor

Person, recommended

The cast members of the work.

actor.name

Text, recommended

Actor name.

actor.sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the actor. Example: IMDB, Wikipedia.

description

Text, recommended

A synopsis of the work. Plot synopses are preferred to factual summaries.

director

Person, recommended

The director of the work.

director.name

Text, recommended

Director name.

director.sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the director. Example: IMDB, Wikipedia.

hasPart

TVClip or Clip, recommended

Short videos related to the Movie (use Clip), TVEpisode, TVSeries or TVSeason (use TVClip).

hasPart.description

Text, recommended

One of the following values:

  • "trailer": A preview or advertisement of the work.
  • "behind_the_scenes": A summary of the production of the work.
  • "highlight": A contiguous scene from the work.
hasPart.potentialAction

WatchAction, recommended

Watch action(s) for the clip. See WatchAction Properties.

hasPart.timeRequired

Text, recommended

Duration of the clip in ISO 8601 format, "PT2M5S" (2min 5sec).

image

Repeated field of ImageObject or URL, recommended

Images related to the work.

Additional image guidelines:

  • Every page must contain at least one image (whether or not you include markup). Google will pick the best image to display in Search results based on the aspect ratio and resolution.
  • Image URLs must be crawlable and indexable.
  • Images must represent the marked up content.
  • Images must be in .jpg, .png, or. gif format.
  • For best results, provide multiple high-resolution images (minimum of 50K pixels when multiplying width and height) with the following aspect ratios: 16x9, 4x3, and 1x1.

For example:

"image": [
    "https://example.com/photos/1x1/photo.jpg",
    "https://example.com/photos/4x3/photo.jpg",
    "https://example.com/photos/16x9/photo.jpg"
   ]
image.height

Integer, recommended

Height of the image in pixels.

image.width

Integer, recommended

Width of the image in pixels.

image.url

URL, recommended

URL where the image can be fetched.

name

Text, required

Name of the work.

potentialAction

WatchAction, required

Watch action(s) for the Movie, TVEpisode, TVSeason or TVSeries. See WatchAction Properties for details.

releasedEvent

PublicationEvent, recommended

Details about the original release of the work.

releasedEvent.startDate

Date, recommended

Original broadcast/theatrical release date of the work, in ISO 8601 format.

releasedEvent.location

Country, recommended

Country in which the work was released on the above startDate.

releasedEvent.location.name

Text, recommended

The 2-letter ISO 3166 country code.

sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the work. Example: IMDB, Wikipedia.

url

URL, recommended

URL to partner's landing page for the work.

Movie properties

Use AMP for your movie list pages, and define each movie as a Movie item, inclusive of the common properties above and the following movie-specific properties.

Properties
duration

Text, recommended

Runtime of the movie in ISO 8601 format (for example, "PT2H22M" (142 minutes)).

TV episode properties

Each episode should defined as a TVEpisode item, inclusive of the common properties and the following episode-specific properties.

Properties
episodeNumber

Integer, required

Position of the episode within an ordered group of episodes for a given season.

partOfSeason

TVSeason, required

The season of the episode.

partOfSeason.seasonNumber

Integer, required

Position of the season within an ordered group of seasons.

partOfSeries

TVSeries, required

The series of the episode.

partOfSeries.name

Text, required

Name of the TV series.

partOfSeries.sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the series. Example: IMDB, Wikipedia.

TV season properties

Each season should be defined as a TVSeason item with the following properties.

Properties
@id

URL, recommended

Globally unique ID of the season in the form of a URL. The ID should be stable and not change over time. The URL is treated as an opaque string and does not have to be a working link.

name

Text, recommended

Name of the TVSeason, if it differs from the series name.

partOfSeries

TVSeries, required

The series of the season.

partOfSeries.name

Text, required

Name of the TV series.

partOfSeries.sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the series. Example: IMDB, Wikipedia.

potentialAction

ViewAction, recommended

View action(s) for the season. See ViewAction Properties.

releasedEvent

PublicationEvent, recommended

Details about the original release of the first episode of the season.

releasedEvent.location

Country, recommended

Country in which the first episode of the season was broadcast on the above startDate.

releasedEvent.location.name

Text, recommended

The 2-letter ISO 3166 country code.

releasedEvent.startDate

Date, recommended

Original broadcast date of the first episode of the season, in ISO 8601 format.

sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the season. Example: IMDB, Wikipedia.

seasonNumber

Integer, required

Position of the season within an ordered group of seasons.

url

URL, recommended

URL to partner's season landing page.

TV series properties

Each series should be defined as a TVSeries item with the following properties.

Properties
@id

URL, recommended

Globally unique ID of the series in the form of a URL. The ID should be stable and not change over time. The URL is treated as an opaque string and does not have to be a working link.

actor

Person, recommended

The main cast of the series.

actor.name

Text, recommended

Name of the actor.

actor.sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the actor. Example: IMDB, Wikipedia.

name

Text, required

Name of the TV series.

potentialAction

ViewAction, recommended

View action(s) for the season. See ViewAction Properties.

releasedEvent

PublicationEvent, recommended

Details about the original release of the first episode of the series.

releasedEvent.location

Country, recommended

Country in which the first episode of the series was broadcast on the above startDate.

releasedEvent.location.name

Text, recommended

The 2-letter ISO 3166 country code.

releasedEvent.startDate

Date, recommended

Original broadcast date of the first episode of the series, in ISO 8601 format.

sameAs

URL, recommended

URL to a reference web page that unambiguously identifies the series. Example: IMDB, Wikipedia.

url

URL, recommended

URL to partner's series landing page.

WatchAction properties

The following properties are required for each WatchAction.

Properties
expectsAcceptanceOf

Offer, required

A container for the action conditions.

expectsAcceptanceOf.availabilityEnds

Date, required

Date after which the action is no longer available, in ISO 8601 format.

expectsAcceptanceOf.availabilityStarts

Date, required

Date after which the action is available, in ISO 8601 format.

expectsAcceptanceOf.category

Text, required

One of the following values:

  • "rental": The action is available to the user after purchase for a finite amount of time.
  • "purchase": The action is available to the user after purchase for an indefinite amount of time.
  • "subscription": The action is included with a subscription to the partner itself.
  • "externalSubscription": The action is included with a subscription to an entity other than the action partner, e.g. HBO GO requires a cable provider.
  • "free": The action is available with no purchase or subscription required of the user. The action may require a user login or contain ads.
expectsAcceptanceOf.eligibleRegion

Country, required

Countries in which the action is available.

expectsAcceptanceOf.eligibleRegion.name

Text, required

The ISO 3166 country code.

target

EntryPoint, required

A container for the action target.

target.actionPlatform

Text, required

The platform(s) on which the link works. One or more of the following:

  • http://schema.org/DesktopWebPlatform: Works on desktop web browsers.
  • http://schema.org/MobileWebPlatform: Works on mobile web browsers.
  • http://schema.org/AndroidPlatform: Works on Android native app.
  • http://schema.org/IOSPlatform: Works on iOS native app.
  • http://schema.googleapis.com/GoogleVideoCast: Works on a Chromecast device.
target.urlTemplate

URL, required

Link(s) to content.

ViewAction properties

The following properties are required for each ViewAction.

Properties
target.actionPlatform

Text, required

The platform(s) on which the link works. One or more of the following:

  • http://schema.org/DesktopWebPlatform: Works on desktop web browsers.
  • http://schema.org/MobileWebPlatform: Works on mobile web browsers.
  • http://schema.org/AndroidPlatform: Works on Android native app.
  • http://schema.org/IOSPlatform: Works on iOS native app.
  • http://schema.googleapis.com/GoogleVideoCast: Works on a Chromecast device.
target.urlTemplate

URL, required

Link(s) to content.

For additional details on how to mark up actions, see Provide actions.

Send feedback about...