TV & Movies

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

Use cases

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.

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.

Examples

Movie Example

{
  "@context": "http://schema.org",
  "@id": "12546432",
  "@type": "Movie",
  "name": "Forrest Gump",
  "url": "http://www.example.com/forrest_gump",
  "description": "A man with a low I.Q. has accomplished great things in his life and been present during significant historic events.",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "1994-07-06",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": [
      {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.example.com/forrest_gump?autoplay=true",
        "inLanguage": "en",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      {
        "@type": "EntryPoint",
        "urlTemplate": "android-app://com.app.foo/bar/forrest_gump?autoplay=true",
        "inLanguage": "en",
        "actionPlatform": "http://schema.org/AndroidPlatform"
      }
    ],
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "availabilityStarts": "2015-01-01T00:00",
      "availabilityEnds": "2015-12-31T00:00",
      "category": "subscription",
      "name": "Hulu Plus",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Hulu",
        "sameAs": "http://www.hulu.com/"
      },
      "eligibleRegion": {
        "@type": "Country",
        "name": "US"
      }
    }
  },
  "hasPart": {
    "@type": "Clip",
    "description": "trailer",
    "timeRequired": "PT2M5S",
    "potentialAction": {
      "@type": "WatchAction",
      "target": [
        {
          "@type": "EntryPoint",
          "urlTemplate": "http://www.example.com/watch/2356866",
          "inLanguage": "en",
          "actionPlatform": [
            "http://schema.org/DesktopWebPlatform",
            "http://schema.org/MobileWebPlatform",
            "http://schema.org/IOSPlatform",
            "http://schema.googleapis.com/GoogleVideoCast"
          ]
        },
        {
          "@type": "EntryPoint",
          "urlTemplate": "android-app://com.app.foo/bar/watch/2356866",
          "inLanguage": "en",
          "actionPlatform": "http://schema.org/AndroidPlatform"
        }
      ],
      "expectsAcceptanceOf": {
        "category": "free",
        "availabilityStarts": "2014-09-01T00:00",
        "availabilityEnds": "2015-09-01T00:00",
        "eligibleRegion": {
          "@type": "Country",
          "name": "US"
        }
      }
    }
  },
  "image": {
    "@type": "ImageObject",
    "url": "https://upload.wikimedia.org/wikipedia/en/6/67/Forrest_Gump_poster.jpg"
  },
  "sameAs": "http://www.imdb.com/title/tt0109830/",
  "actor": {
    "@type": "Person",
    "name": "Tom Hanks",
    "sameAs": "http://www.imdb.com/name/nm0000158/"
  },
  "director": {
    "@type": "Person",
    "name": "Robert Zemeckis",
    "sameAs": "http://www.imdb.com/name/nm0000709/"
  },
  "duration": "PT2H22M"
}

TVEpisode Example

{
  "@context": "http://schema.org",
  "@id": "2356865",
  "@type": "TVEpisode",
  "name": "The Occupation Recalibration",
  "episodeNumber": 13,
  "partOfSeason": {
    "@type": "TVSeason",
    "seasonNumber": 7
  },
  "partOfSeries": {
    "@type": "TVSeries",
    "name": "The Big Bang Theory",
    "sameAs": "http://www.imdb.com/title/tt0898266/"
  },
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2014-01-09",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "potentialAction": [
    {
      "@type": "WatchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.example.com/big_bang_theory/s7/e13",
        "inLanguage": "en",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      "expectsAcceptanceOf": [
        {
          "@type": "Offer",
          "category": "free",
          "availabilityStarts": "2014-09-01T00:00",
          "availabilityEnds": "2014-11-01T00:00",
          "eligibleRegion": [
            {
              "@type": "Country",
              "name": "US"
            },
            {
              "@type": "Country",
              "name": "CA"
            }
          ]
        },
        {
          "@type": "Offer",
          "category": "externalSubscription",
          "availabilityStarts": "2014-11-01T00:00",
          "availabilityEnds": "2015-03-01T00:00",
          "seller": {
            "@type": "Organization",
            "name": "Comcast",
            "sameAs": "http://xfinity.comcast.net/"
          }
        }
      ]
    },
    {
      "@type": "WatchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.example.com/big_bang_theory/s7/e13?autoplay=true",
        "inLanguage": "en",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      "expectsAcceptanceOf": [
        {
          "@type": "Offer",
          "category": "free",
          "availabilityStarts": "2014-09-08T00:00",
          "availabilityEnds": "2014-09-17T00:00",
          "eligibleRegion": [
            {
              "@type": "Country",
              "name": "US"
            },
            {
              "@type": "Country",
              "name": "CA"
            }
          ]
        },
        {
          "@type": "Offer",
          "category": "subscription",
          "availabilityStarts": "2014-09-01T00:00",
          "availabilityEnds": "2015-09-01T00:00",
          "name": "CBS All Access",
          "price": 5.99,
          "priceCurrency": "USD",
          "seller": {
            "@type": "Organization",
            "name": "CBS",
            "sameAs": "http://www.cbs.com/"
          }
        }
      ]
    }
  ],
  "hasPart": {
    "@type": "TVClip",
    "description": "trailer",
    "timeRequired": "PT2M5S",
    "potentialAction": {
      "@type": "WatchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.example.com/vid/2356866",
        "inLanguage": "en",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      "expectsAcceptanceOf": {
        "category": "free",
        "availabilityStarts": "2014-09-01T00:00",
        "availabilityEnds": "2015-09-01T00:00"
      }
    }
  },
  "image": {
    "@type": "ImageObject",
    "height": 600,
    "width": 400,
    "url": "http://www.example.com/105987_wb_0721bc.jpg"
  },
  "sameAs": "http://www.imdb.com/title/tt3337730/",
  "description": "Sheldon tries to relax after he is forced to take a vacation. (TV-PG D, L)",
  "actor": [
    {
      "@type": "Person",
      "name": "Jim Parsons",
      "sameAs": "http://www.imdb.com/name/nm1433588/"
    },
    {
      "@type": "Person",
      "name": "Kaley Cuoco-Sweeting",
      "sameAs": "http://www.imdb.com/name/nm0192505/"
    }
  ],
  "director": {
    "@type": "Person",
    "name": "Mark Cendrowski",
    "sameAs": "http://www.imdb.com/name/nm0148252"
  }
}

TVSeason Example

{
  "@context": "http://schema.org",
  "@id": "312675",
  "@type": "TVSeason",
  "sameAs": "http://en.wikipedia.org/wiki/The_Big_Bang_Theory_%28season_4%29",
  "url": "http://www.example.com/big_bang_theory/season4",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2010-09-23",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "seasonNumber": 4,
  "partOfSeries": {
    "@type": "TVSeries",
    "name": "The Big Bang Theory",
    "sameAs": "http://www.imdb.com/title/tt0898266/",
    "url": "http://www.example.com/big_bang_theory/"
  },
  "potentialAction": [
  {
    "@type": "ViewAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/big_bang_theory/season4/purchase",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.org/AndroidPlatform"
      ]
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "availabilityStarts": "2015-01-01T00:00",
      "availabilityEnds": "2015-12-31T00:00",
      "category": "purchase",
      "name": "High definition",
      "price": 28.99,
      "priceCurrency": "USD",
      "eligibleRegion": {
        "@type": "Country",
        "name": "US"
      }
    }
  },
  {
      "@type": "WatchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.example.com/big_bang_theory/season4/watch?autoplay=true",
        "inLanguage": "en",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      "expectsAcceptanceOf": [
        {
          "@type": "Offer",
          "category": "free",
          "availabilityStarts": "2014-09-08T00:00",
          "availabilityEnds": "2014-09-17T00:00",
          "eligibleRegion": [
            {
              "@type": "Country",
              "name": "US"
            },
            {
              "@type": "Country",
              "name": "CA"
            }
          ]
        },
        {
          "@type": "Offer",
          "category": "subscription",
          "availabilityStarts": "2014-09-01T00:00",
          "availabilityEnds": "2015-09-01T00:00",
          "name": "CBS All Access",
          "price": 5.99,
          "priceCurrency": "USD",
          "eligibleRegion": {
        	"@type": "Country",
        	"name": "US"
      	  },
          "seller": {
            "@type": "Organization",
            "name": "CBS",
            "sameAs": "http://www.cbs.com/"
          }
        }
      ]
    }
  ]
}

TVSeries Example

{
  "@context": "http://schema.org",
  "@id": "1243759",
  "@type": "TVSeries",
  "name": "Breaking Bad",
  "sameAs": "http://www.imdb.com/title/tt0903747/",
  "url": "http://www.example.com/breaking_bad/",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2008-01-20",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "actor": [
    {
      "@type": "Person",
      "name": "Bryan Cranston",
      "sameAs": "http://www.imdb.com/name/nm0186505/"
    },
    {
      "@type": "Person",
      "name": "Aaron Paul",
      "sameAs": "http://www.imdb.com/name/nm0666739/"
    }
  ],
  "potentialAction": [
  {
    "@type": "ViewAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/breaking_bad/purchase",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.org/AndroidPlatform"
      ]
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "availabilityStarts": "2015-01-01T00:00",
      "availabilityEnds": "2015-12-31T00:00",
      "category": "purchase",
      "name": "High definition",
      "price": 89.99,
      "priceCurrency": "USD",
      "eligibleRegion": {
        "@type": "Country",
        "name": "US"
      }
    }
  },
  {
      "@type": "WatchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.example.com/breaking_bad/watch?autoplay=true",
        "inLanguage": "en",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      "expectsAcceptanceOf": [
        {
          "@type": "Offer",
          "category": "free",
          "availabilityStarts": "2014-09-08T00:00",
          "availabilityEnds": "2014-09-17T00:00",
          "eligibleRegion": [
            {
              "@type": "Country",
              "name": "US"
            },
            {
              "@type": "Country",
              "name": "CA"
            }
          ]
        },
        {
          "@type": "Offer",
          "category": "subscription",
          "availabilityStarts": "2014-09-01T00:00",
          "availabilityEnds": "2015-09-01T00:00",
          "name": "Example",
          "price": 5.99,
          "priceCurrency": "USD",
          "eligibleRegion": {
        	"@type": "Country",
        	"name": "US"
      	  },
          "seller": {
            "@type": "Organization",
            "name": "Example",
            "sameAs": "http://www.example.com/"
          }
        }
      ]
    }
  ]
}

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.
`name`	Text, required Name of the work.
`url`	URL, recommended URL to partner's landing page for the work.
`description`	Text, recommended A synopsis of the work. Plot synopses are preferred to factual summaries.
`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.
`potentialAction`	WatchAction, required Watch action(s) for the `Movie`, `TVEpisode`, `TVSeason` or `TVSeries`. See WatchAction Properties for details.
`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.timeRequired`	Text, recommended Duration of the clip in ISO 8601 format, `"PT2M5S"` (2min 5sec).
`hasPart.potentialAction`	WatchAction, recommended Watch action(s) for the clip. See WatchAction Properties.
`image`	ImageObject, recommended* Images related to the work. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available. PNG and JPG preferred. *Mark up an image to include it in the rich card. If you don't mark up a specific image, a prominent image from the page will be used in the card. Every page must contain at least one image (whether or not you include markup).
`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.
`sameAs`	URL, recommended URL to a reference web page that unambiguously identifies the work. Example: IMDB, Wikipedia.
`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.
`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.

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

Properties
`duration`	Text, recommended Runtime of the movie in ISO 8601 format, e.g. "PT2H22M" (142 minutes).

duration

Text, recommended

Runtime of the movie in ISO 8601 format, e.g. "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.
`sameAs`	URL, recommended URL to a reference web page that unambiguously identifies the season. Example: IMDB, Wikipedia.
`url`	URL, recommended URL to partner's season landing page.
`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.startDate`	Date, recommended Original broadcast date of the first episode of the season, in ISO 8601 format.
`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.
`seasonNumber`	Integer, required Position of the season within an ordered group of seasons.
`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.

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.
`name`	Text, required Name of the TV series.
`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.
`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.startDate`	Date, recommended Original broadcast date of the first episode of the series, in ISO 8601 format.
`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.
`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.

WatchAction properties

The following properties are required for each WatchAction.

Properties
`target`	EntryPoint, required A container for the action target.
`target.urlTemplate`	URL, required Link(s) to content.
`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.
`expectsAcceptanceOf`	Offer, required A container for the action conditions.
`expectsAcceptanceOf.eligibleRegion`	Country, required Countries in which the action is available.
`expectsAcceptanceOf.eligibleRegion.name`	Text, required The ISO 3166 country code.
`expectsAcceptanceOf.availabilityStarts`	Date, required Date after which the action is available, in ISO 8601 format.
`expectsAcceptanceOf.availabilityEnds`	Date, required Date after which the action is no longer 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.

ViewAction properties

The following properties are required for each ViewAction.

Properties

Properties
`target.urlTemplate`	URL, required Link(s) to content.
`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.

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.

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