Data Specification - Shows and Movies

For each show and movie in your content catalog, you must provide markup for the following entity types:

  • Movies - Required
  • TVSeries - Required
  • TVEpisode - Required
  • TVSeason - Recommended

Use the specification below to generate the appropriate Content markup and Action markup for each entity in your catalog.

Content Markup Properties

Your content markup specifies metadata about the entities in your catalog, enabling Google to understand exactly what content your Media Actions will initiate. The specific properties of content markup vary by entity type:

Movie

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]

Where xx represents the language that this entity is in. Each root entity context should have it's @language set to the appropriate language code.
@type Text Required - Always set to Movie for movies.
@id URL Required - A globally unique ID for the content in URI format. The ID should be stable and not change over time. It will be treated as an opaque string and does not have to be a working link.

If you have an ID that is not in an URI format and it represents this entity uniquely across your entire catalog, you can prepend your domain to the id. For example, if the id is 1234abc, the @id would be https://example.com/1234abc. The domain used for the @id value must be owned by your organization.
url URL Required - The canonical URL for the movie on your site. Must be globally unique. This link is used to help accurately reconcile the content in your feed with the content in Google's databases. For playback, the target.urlTemplate detailed in the Action Markup Properties section of the documentation will be used.
name Text Required - The name of the movie.
potentialAction WatchAction Required - Watch action(s) for the Movie. See Action Markup Properties for details.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the movie, eg Wikipedia page for the movie. This should be distinct from the url property above.
releasedEvent PublicationEvent Recommended - Details about the original release of the movie.
description Text Recommended - A synopsis of the movie. Plot synopses are preferred to factual summaries. Please limit to 300 characters.
duration Text Recommended - Runtime of the movie in (ISO 8600 format)[http://en.wikipedia.org/wiki/ISO_8601]
director Person Recommended - The director(s) of the movie.
actor Person Recommended - The cast member(s) of the movie.
image ImageObject Recommended - Images related to the movie. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
hasPart Clip Recommended - Short videos related to the Movie.

TVSeries

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]

Where xx represents the language that this entity is in. Each root entity context should have it's @language set to the appropriate language code.
@type Text Required - Always set to TVSeries for tv series.
@id URL Required - A globally unique ID for the content in URI format. The ID should be stable and not change over time. It will be treated as an opaque string and does not have to be a working link.

We recommend that you use the same value for url and @id (as long as the URL for the entity is unique across your catalog). The domain used for the @id value must be owned by your organization.
url URL Required - The canonical URL for the content on your site. Must be globally unique. This link is used to help accurately reconcile the content in your feed with the content in Google's databases. For playback, the target.urlTemplate detailed in the Action Markup Properties section of the documentation will be used.
name Text Required - The name of the show.
potentialAction WatchAction Required - Watch action(s) for the TVSeries. See Action Markup Properties for details.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the show, eg Wikipedia page for the show. This should be distinct from the url property above.
releasedEvent PublicationEvent Recommended - Details about the original release of the show.
description Text Recommended - A synopsis of the show. Plot synopses are preferred to factual summaries. Please limit to 300 characters.
actor Person Recommended - The cast member(s) of the show.
image ImageObject Recommended - Images related to the show. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
hasPart TVClip Recommended - Short videos related to the TVSeries.

TVEpisode

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]

Where xx represents the language that this entity is in. Each root entity context should have it's @language set to the appropriate language code.
@type Text Required - Always set to TVEpisode for tv episodes.
@id URL Required - A globally unique ID for the content in URI format. The ID should be stable and not change over time. It will be treated as an opaque string and does not have to be a working link.

We recommend that you use the same value for url and @id (as long as the URL for the entity is unique across your catalog). The domain used for the @id value must be owned by your organization.
url URL Required - The canonical URL for the content on your site. This link is used to help accurately reconcile the content in your feed with the content in Google's databases. For playback, the target.urlTemplate detailed in the Action Markup Properties section of the documentation will be used.
name Text Required - The name of the episode.
episodeNumber Integer Required - Position of the episode within an ordered group of episodes for a given season. The episodeNumber should restart for each season (i.e. the first episode of each season should be “1”)
partOfSeason TVSeason Required - The season of the episode.
partOfSeason.@type Text Required - Always set to TVSeason for this property.
partOfSeason.@id URL Required - The @id you're using for the TVSeason that this episode is part of.
partOfSeason.seasonNumber Integer Required - Position of the season within an ordered group of seasons.
partOfSeries TVSeries Required - The series that the episode belongs to.
partOfSeries.@type Text Required - Always set to TVSeries for this property.
partOfSeries.@id URL Required - The @id you're using for the TVSeries that this episode is part of.
partOfSeries.name Text Required - Name of the TV series.
partOfSeries.sameAs Text Recommended - URL to a reference web page that unambiguously identifies the show, eg Wikipedia page for the show.
potentialAction WatchAction Required - Watch action(s) for the TVEpisode. See Action Markup Properties for details.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the episode, eg Wikipedia page for the episode. This should be distinct from the url property above.
releasedEvent PublicationEvent Recommended - Details about the original release of the episode.
description Text Recommended - A synopsis of the episode. Plot synopses are preferred to factual summaries. Please limit to 300 characters.
actor Person Recommended - The cast member(s) of the episode.
image ImageObject Recommended - Images related to the episode. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
hasPart TVClip Recommended - Short videos related to the TVEpisode.

TVSeason

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]

Where xx represents the language that this entity is in. Each root entity context should have it's @language set to the appropriate language code.
@type Text Required - Always set to TVSeason for tv seasons.
@id URL Required - A globally unique ID for the content in URI format. The ID should be stable and not change over time. It will be treated as an opaque string and does not have to be a working link.

We recommend that you use the same value for url and @id (as long as the URL for the entity is unique across your catalog). The domain used for the @id value must be owned by your organization.
url URL Required - The canonical URL for the content on your site. This link is used to help accurately reconcile the content in your feed with the content in Google's databases. For playback, the target.urlTemplate detailed in the Action Markup Properties section of the documentation will be used.
name Text Required - The name of the season.
seasonNumber Integer Required - Position of the season within an ordered group of seasons.
partOfSeries TVSeries Required - The series that the season belongs to.
partOfSeries.@type Text Required - Always set to TVSeries for this property.
partOfSeries.@id URL Required - The @id you're using for the TVSeries that this season is part of.
partOfSeries.name Text Required - Name of the TV series.
partOfSeries.sameAs Text Recommended - URL to a reference web page that unambiguously identifies the show, eg Wikipedia page for the show.
potentialAction WatchAction Required - Watch action(s) for the TVSeason. See Action Markup Properties for details.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the season, eg Wikipedia page for the season.
releasedEvent PublicationEvent Recommended - Details about the original release of the season.
description Text Recommended - A synopsis of the season. Plot synopses are preferred to factual summaries. Please limit to 300 characters.
actor Person Recommended - The cast member(s) of the season.
image ImageObject Recommended - Images related to the season. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
hasPart TVClip Recommended - Short videos related to the TVSeason.

Live TV

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]

Where xx represents the language that this entity is in. Each root entity context should have it's @language set to the appropriate language code.
@type Text Required - Always set to BroadcastService for Live TV.
@id URL Required - A globally unique ID for the content in URI format. The ID should be stable and not change over time. It will be treated as an opaque string and does not have to be a working link.

We recommend that you use the same value for url and @id (as long as the URL for the entity is unique across your catalog). The domain used for the @id value must be owned by your organization.
url URL Required - The canonical URL that represents the live TV service on your site for the particular network you are marking up. This link is used to help accurately reconcile the content in your feed with the content in Google's databases. For playback, the target.urlTemplate detailed in the Action Markup Properties section of the documentation will be used.
name Text Required - The name of the network.
broadcastDisplayName Text Required - The display name for the network that users may typically see in program guides etc. The value may be the same as the name value.
potentialAction WatchAction Required - Watch action(s) for the content. See Action Markup Properties for details.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the network, eg Wikipedia page for the network.
image ImageObject Recommended - Images related to the Live TV service. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.

Quick Checks

  • For the entity level url property, please ensure that you are providing the canonical URL. The URL you provide should be unique for each entity, for example do not use the same URL for a TVSeries as you would for a TVEpisode.
  • @id is intended to be a unique ID for an entity across your entire catalog and should comply with the following guidelines:
    • Does not ever change
    • Unique per content type and across content types. For example, you may not use the same @id for a TVSeries and a TVEpisode
    • The same @id should be used throughout your structured data wherever the entity is referenced, for example the partOfSeries.@id for a TVEpisode should match the @id used for the main TVSeries definition
    • Must be in the form of a URI (does not need to be a working URL).
    • The domain used for the @id value must be owned by your organization.

In general we recommend that you use the same value for url and @id as long as the URL for the entity is unique across your catalog.

Action Markup Properties

Your Action markup specifies:

  • The deeplink(s) to use for a given piece of content on each of your platforms (e.g. iOS, Cast)
  • The availability information (e.g. geo-restrictions, availability windows, cost) for a given piece of content on your service

For video content, such as shows and movies, Action markup takes the form of a WatchAction. These are nested/marked up in the potentialAction block of the Content markup.

Watch Action Properties

Property Expected type Description
@type Text Required - Always set to WatchAction
target EntryPoint Required - A container for the action target. Can be an array if there are different deeplinks for different platforms
target.@type Text Required - Always set to EntryPoint.
target.urlTemplate URL Required - This is the link that will be used to initiate playback of your content on your app. For voice-activated speaker integrations, for example, this link will be passed to your Cast receiver app. See Deeplink Requirements for detailed requirements.
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.
  • http://schema.googleapis.com/GoogleAudioCast: Not applicable to TV-Movies content.
Note: If a link you're providing also works on your AndroidTV app, also include http://schema.org/AndroidTVPlatform in the list of platforms for that link. Do not use this type to provide a distinct link for AndroidTV that's different from your Android mobile or universal link.
You must supply a deeplink for every platform where you are able to serve content.
actionAccessibilityRequirement ActionAccessSpecification Required - A set of requirements that must be fulfilled in order to access a consume action. See Action Access Specification Properties.

Action Access Specification Properties

Property Expected type Description
actionAccessibilityRequirement.@type Text Required - Always set to ActionAccessSpecification
actionAccessibilityRequirement.category Text Required - A category for the item. Use one of the following values:
  • nologinrequired: The action is available and free to the user with no purchase or login to access content.
  • free: The action is available and free to the user, but requires the user to be logged in/authenticated with a free subscription.
  • subscription: The action requires the user to have a subscription and to be logged in/authenticated with a paid subscription to access the content.
  • externalsubscription: The action is included with a subscription to an entity other than your service, e.g. HBO GO requires a cable provider.
  • 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.
actionAccessibilityRequirement.availabilityStarts Date Required - Date after which the action is available, in ISO 8601 format (including timezone). Can be a date in the future
actionAccessibilityRequirement.availabilityEnds Date Required - Date after which the action is no longer available, in ISO 8601 format (including timezone). Must be equal or greater than 72 hours after availabilityStarts.
actionAccessibilityRequirement.eligibleRegion Country Required - Countries in which the action is available.
actionAccessibilityRequirement.eligibleRegion.@type Text Required - Always set to Country.
actionAccessibilityRequirement.eligibleRegion.name Text Required - The ISO 3166 country code.
actionAccessibilityRequirement.requiresSubscription MediaSubscription Required - A subscription which must be held by the user in order to access the action. See Media Subscription Properties.
expectsAcceptanceOf Offer Required with exceptions - Offer associated with purchasing the action. This should represent the non-subscription purchase offer or the additional purchase requirements for subscribers. If the offer price is 0.00, this property can be left out. See Offer Properties.

Media Subscription Properties

Property Expected type Description
requiresSubscription.@type Text Required - Always set to MediaSubscription
requiresSubscription.@id URL Required - The unique id for the subscription. Note that if content is accessible with several different subscriptions/packages, each must have a unique id.
requiresSubscription.name Text Required - The name of the subscription. Note that if content is accessible with several different subscriptions/packages, the name you use should match the name/title used in your user authentication system. For example, if a user is able to access content based on subscription to a package called "Package 1" and the authentication system denotes this as "PKG1", use "PKG1" as the name.
For TVE Providers, this is the authenticator name registered with your TVE authenticator. It is a string that uniquely identifies your service name with the TVE Authenticator.
requiresSubscription.sameAs URL Recommended - The page that describes the subscription (or the package if you have multiple packages).
requiresSubscription.authenticator Organization Required Use only if category is externalsubscription - Authenticator details if authentication is done with an external provider, eg TVE.
requiresSubscription.authenticator.@type Text Required - Always set to Organization
requiresSubscription.authenticator.name Text Required - The name of the authentication service. For TVE providers, set to 'TVE'
expectsAcceptanceOf Offer Recommended - Offer associated with purchasing the Media Subscription. See Offer Properties.

Offer Properties

Property Expected type Description
expectsAcceptanceOf.@type Text Required - Always set to Offer
expectsAcceptanceOf.price Number Required - The offer price for a subscription or purchase of an action.
expectsAcceptanceOf.priceCurrency Date Required - The currency (in 3-letter ISO 4217 format) of the price.
expectsAcceptanceOf.seller Organization Optional - The organization which offers the subscription/purchase of the action.
expectsAcceptanceOf.seller.@type Text Optional - Always set to Organization.
expectsAcceptanceOf.seller.name Text Optional - The name of the seller.
expectsAcceptanceOf.seller.sameAs Text Optional - URL to a reference web page that unambiguously identifies the seller, eg seller's homepage

NOTE: The offer block is only required if the expectsAcceptanceOf.price is greater than 0.00.

Access Requirement Examples

In order to faciliate implementation of access requirements, a few examples are shown below. Note that you can mark up different access requirements across different platforms. For example, your content could be free on Desktop devices but require a subscription to watch on Android/iOS devices.

Click to expand for an example of each type of access that can be specified.

Free

No Login Required

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "nologinrequired",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
  • The lack of a payment option indicates no payment required for consumption
  • The category set to 'nologinrequired' indicates this action does not require an account

Login Required

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "free",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
  • The lack of a payment option indicates no payment required for consumption
  • The category set to 'free' indicates this action is free but requires an account

Single Subscription

No Additional Cost

Offer is available through a subscription without additional cost.

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "requiresSubscription": {
      "@type": "MediaSubscription",
      "@id": "[partner determined string]"
      "name": "Basic Membership",
      "expectsAcceptanceOf": {
        "@type": "Offer",
        "price": 8.99,
        "priceCurrency": "USD"
      }
    }
  }
}
  • The requiresSubscription block indicates that the user needs an account to access the content
  • The presence of an offer within the MediaSubscription block indicates that the subscription is not free
  • The lack of an offer within the ActionAccessSpecification block indicates that there is no additional charge for this action

Additional Cost

Offer is available through a subscription and has an additional cost.

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "requiresSubscription": {
      "@type": "MediaSubscription",
      "@id": "[partner determined string]"
      "name": "Basic Membership",
      "expectsAcceptanceOf": {
        "@type": "Offer",
        "price": 8.99,
        "priceCurrency": "USD",
      },
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 4.99,
      "priceCurrency": "USD"
    }
  }
}
  • The requiresSubscription block indicates that the user needs an account to access the content
  • The presence of an offer within the MediaSubscription block indicates that the subscription is not free
  • The presence of an offer within the ActionAccessSpecification block indicates that there is an additional charge beyond the subscription for this action

Multi-tiered Subscription

No Additional Cost

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "requiresSubscription": [
      {
        "@type": "MediaSubscription",
        "name": "Basic Package",
        "@id": "[partner determined string]",
        "expectsAcceptanceOf": {
          "@type": "Offer",
          "price": 8.99,
          "priceCurrency": "USD"
        },
      },
      {
        "@type": "MediaSubscription",
        "name": "Premium Package",
        "@id": "[partner determined string]"
        "expectsAcceptanceOf": {
          "@type": "Offer",
          "price": 20.99,
          "priceCurrency": "USD"
        },
      }
    ]
  }
}
  • The requiresSubscription block indicates that the user needs an account to access the content
  • The presence of an offer within the MediaSubscription block indicates that the subscription is not free
  • The presence of multiple offers indicates this action is available through different subscriptions
  • The lack of an offer within the ActionAccessSpecification block indicates that there is no additional charge for this action

Additional Cost

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "requiresSubscription": [
      {
        "@type": "MediaSubscription",
        "name": "Basic Package",
        "@id": "[partner determined string]",
        "expectsAcceptanceOf": {
          "@type": "Offer",
          "price": 8.99,
          "priceCurrency": "USD"
        },
      },
      {
        "@type": "MediaSubscription",
        "name": "Premium Package",
        "@id": "partner determined string]"
        "expectsAcceptanceOf": {
          "@type": "Offer",
          "price": 20.99,
          "priceCurrency": "USD"
        },
      }
    ],
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 4.99,
      "priceCurrency": "USD"
    }
  }
}
  • The requiresSubscription block indicates that the user needs an account to access the content
  • The presence of an offer within the MediaSubscription block indicates that the subscription is not free
  • The presence of an offer within the ActionAccessSpecification block indicates that there is an additional charge beyond the subscriptions for this action

3rd Party Subscription

{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "externalsubscription"
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "requiresSubscription": {
      "@type": "MediaSubscription",
      "name": "Basic Package",
      "@id": "[partner determined string]",
      "expectsAcceptanceOf": {
        "@type": "Offer",
        "price": 8.99,
        "priceCurrency": "USD"
      },
      "authenticator": {
        "@type": "Organization",
        "name": "TVE",
        "sameAs": "http://www.tveverywherenow.com/"
      }
    }
  }
}
  • The requiresSubscription block indicates that the user needs an account to access the content
  • The lack of an offer within the ActionAccessSpecification block indicates that there is no additional charge for this action
  • The presence of the authenticator indicates that authentication is handled by a separate party and therefore naming for the package may be dependent on that 3P’s naming scheme

PayPerView

Purchase

{
  "actionAccessibilityRequirement": [{
    "@type": "ActionAccessSpecification",
    "category": "purchase",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Example",
        "sameAs": "http://www.example.com/"
      }
    }
  },
  {
    "@type": "ActionAccessSpecification",
    "category": "purchase",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "GB"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 10.99,
        "priceCurrency": "GBP",
        "seller": {
          "@type": "Organization",
          "name": "Example2",
          "sameAs": "http://www.example2.com/"
        }
    }
  }]
}
  • The category set to 'purchase' indicates this action is not free and is available for an indefinite amount of time.

Rental

{
  "actionAccessibilityRequirement": [{
    "@type": "ActionAccessSpecification",
    "category": "rental",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Example",
        "sameAs": "http://www.example.com/"
      }
    }
  },
  {
    "@type": "ActionAccessSpecification",
    "category": "rental",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "GB"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 10.99,
        "priceCurrency": "GBP",
        "seller": {
          "@type": "Organization",
          "name": "Example2",
          "sameAs": "http://www.example2.com/"
        }
    }
  }]
}
  • The category set to 'rental' indicates this action is not free and is available for a finite amount of time.

  • Please adhere to the following restrictions for deeplink styles by platform:
    • For iOS and Chromecast, universal links are required.
    • For Android, universal links are recommended. If you do not yet support the universal link format on Android, the old style android-app://{package_id}/{scheme}/{path}/... URL format can be used.
  • We highly recommend that you implement universal links across all your platforms. For instructions on implementing Universal Links, see: iOS Documentation | Android Documentation.
  • Deeplinks do not need to be canonical
  • Deeplinks may include parameters/tags (e.g. for tracking purposes).

General Action Markup Guidelines

  • The target attribute may be an array of EntryPoint blocks when different deeplinks should used for different platforms
  • The actionAccessibilityRequirement attribute may be an array of ActionAccessSpecification blocks when necessary (e.g. different availability windows for different countries)
  • The actionAccessibilityRequirement.eligibleRegion attribute may be an array of Country blocks
  • The potentialAction attribute may be an array of WatchAction blocks to support different ActionAccessSpecifications on different actionPlatforms. However, you should consolidate to as few WatchAction blocks as possible.
  • For TVSeries Actions, provide the least restrictive actionAccessibilityRequirement.category for the show. For example, if certain episodes are available without login, while others are only available for subscribed users, the TVSeries actionAccessibilityRequirement.category should be nologinrequired. When a user initiates the TVSeries Action, the episode you select to play should take into consideration the access tier of the user. For general guidelines on selection of episodes for TVSeries Actions, see: Watch Actions - Action Behavior
  • To allow for freshness and processing time, we highly recommend that you provide WatchActions in advance of your content being available to users by using availabilityStarts to indicate when we can start serving.

If you encounter a scenario not discussed here, please reach out to your Google contact for assistance.

Complete Examples

Click to expand for an example of each TV/Movie type. A more extensive set of examples is available here.

Movie

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "Movie",
  "@id": "http://www.example.com/forrest_gump",
  "url": "http://www.example.com/forrest_gump",
  "name": "Forrest Gump",
  "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/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
       ]
     },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
       },
       "eligibleRegion": [
         {
            "@type": "Country",
            "name": "US"
         },
         {
            "@type": "Country",
            "name": "CA"
         }
       ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/Forrest_Gump",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "1994-07-06",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "description": "A man with a low I.Q. has accomplished great things in his life and been present during significant historic events.",
  "duration": "PT2H22M",
  "director": {
    "@type": "Person",
    "name": "Robert Zemeckis",
    "sameAs": "https://en.wikipedia.org/wiki/Robert_Zemeckis"
  },
  "actor": {
    "@type": "Person",
    "name": "Tom Hanks",
    "sameAs": "https://en.wikipedia.org/wiki/Tom_Hanks"
  }
}

TVSeries

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVSeries",
  "@id": "http://www.example.com/breaking_bad/",
  "url": "http://www.example.com/breaking_bad/",
  "name": "Breaking Bad",
  "potentialAction": {
    "@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/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
       },
       "eligibleRegion": [
         {
            "@type": "Country",
            "name": "US"
         },
         {
            "@type": "Country",
            "name": "CA"
         }
       ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/Breaking_Bad",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2008-01-20",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "description": "A chemistry teacher with cancer cooks and sells meth to pay for his treatments.",
  "actor": [
    {
      "@type": "Person",
      "name": "Bryan Cranston",
      "sameAs": "https://en.wikipedia.org/wiki/Bryan_Cranston"
    },
    {
      "@type": "Person",
      "name": "Aaron Paul",
      "sameAs": "https://en.wikipedia.org/wiki/Aaron_Paul"
    }
  ]
}

TVEpisode

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVEpisode",
  "@id": "http://www.example.com/big_bang_theory/s7/e14",
  "url": "http://www.example.com/big_bang_theory/s7/e14",
  "name": "The Convention Conundrum",
  "episodeNumber": 14,
  "partOfSeason": {
    "@type": "TVSeason",
    "@id": "http://www.example.com/big_bang_theory/s7",
    "seasonNumber": 7
  },
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "http://www.example.com/big_bang_theory",
    "name": "The Big Bang Theory",
    "sameAs": "https://en.wikipedia.org/wiki/The_Big_Bang_Theory"
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/big_bang_theory/s7/e14?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"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
       },
       "eligibleRegion": [
         {
            "@type": "Country",
            "name": "US"
         },
         {
            "@type": "Country",
            "name": "CA"
         }
       ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/The_Convention_Conundrum",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2014-01-09",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "description": "The gang tries to get tickets to Comic Con.",
  "actor": [
    {
      "@type": "Person",
      "name": "Jim Parsons",
      "sameAs": "https://en.wikipedia.org/wiki/Jim_Parsons"
    },
    {
      "@type": "Person",
      "name": "Kaley Cuoco-Sweeting",
      "sameAs": "https://en.wikipedia.org/wiki/Kaley_Cuoco"
    }
  ]
}

TVSeason

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVSeason",
  "@id": "http://www.example.com/big_bang_theory/s7",
  "url": "http://www.example.com/big_bang_theory/s7",
  "name": "Season 7",
  "seasonNumber": 7,
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "http://www.example.com/big_bang_theory",
    "name": "The Big Bang Theory",
    "sameAs": "https://en.wikipedia.org/wiki/The_Big_Bang_Theory"
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/big_bang_theory/s7/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"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
      },
      "eligibleRegion": [
       {
          "@type": "Country",
          "name": "US"
       },
       {
          "@type": "Country",
          "name": "CA"
       }
      ]
     }
  },
  "sameAs": "https://en.wikipedia.org/wiki/The_Big_Bang_Theory_(season_7)",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2010-09-23",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "description": "The seventh season of Big Bang Theory shows the growing relationship between Penny and Leonard.",
  "actor": [
    {
      "@type": "Person",
      "name": "Jim Parsons",
      "sameAs": "https://en.wikipedia.org/wiki/Jim_Parsons"
    },
    {
      "@type": "Person",
      "name": "Kaley Cuoco-Sweeting",
      "sameAs": "https://en.wikipedia.org/wiki/Kaley_Cuoco"
    }
  ]
}

Live TV

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastService",
  "@id": "http://www.amc.com/livestream",
  "url": "http://www.amc.com/livestream",
  "sameAs": "https://en.wikipedia.org/wiki/AMC_(TV_channel)",
  "name": "AMC",
  "broadcastDisplayName": "AMC",
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
        "@type": "EntryPoint",
        "urlTemplate": "http://www.amc.com/livestream",
        "actionPlatform": [
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/MobileWebPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "externalsubscription",
      "availabilityStarts": "2017-07-21T10:35:29Z",
      "availabilityEnds": "2018-10-21T10:35:29Z",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://www.amc.com/subscription",
        "name": "AMC",
        "sameAs": "http://www.amc.com/subscription",
        "authenticator": {
          "@type": "Organization",
          "name": "TVE"
        }
      },
      "eligibleRegion": [
       {
          "@type": "Country",
          "name": "US"
       },
       {
          "@type": "Country",
          "name": "CA"
       }
     ]
    }
  }
}