The Media Actions feed is a JSON object that contains a collection of entities. An entity is a schema.org object that represents an item in your catalog: a TV episode, a TV series, a movie, a song, an album, and more.

Feed structure
Watch Actions and Listen Actions have different feed structures.
Watch Actions have the following hierarchy: |
Listen Actions have the following hierarchy: |
Data feed envelope
A data feed envelope is the top level object in the Media Actions feed. The object contains an array of content markup objects (entities) that represent all the content in your catalog.
A data feed envelope supports the following properties:
Property | Type | Description |
---|---|---|
@context |
URL | Required - Set to http://schema.org |
@type |
Text | Required - Set to DataFeed . |
dateModified |
DateTime | Required - The last modified date and time of the feed, in ISO 8601 format (including timezone). |
dataFeedElement |
Thing | Required - The entities of your media catalog. |
Data feed envelope template
{
"@context": "http://schema.org",
"@type": "DataFeed",
"dateModified": "2018-07-20T00:44:51Z",
"dataFeedElement": [
{ <CONTENT MARKUP OBJECT 01> },
{ <CONTENT MARKUP OBJECT 02> },
{ <CONTENT MARKUP OBJECT 03> },
...
]
}
Content markup
A content markup object represents a single entity in your catalog: a movie, a TV episode, a TV series, a song, an album, a radio station, etc. The object contains the content's identifier and canonical URL and helps describe the content via metadata.
Content markup template
A content markup object can have an array of Action markup objects, which allows the content to be associated with multiple Action markup objects. For instance, the content can have a different Action markup object per region.
{
"@context": ["http://schema.org", {"@language": "en"}],
"@type": "Movie",
"@id": "http://www.example.com/my_favorite_movie",
"url": "http://www.example.com/my_favorite_movie",
"name": "My Favorite Movie",
"potentialAction": [
{ <ACTION MARKUP OBJECT 01> },
{ <ACTION MARKUP OBJECT 02> }
],
...
}
Action markup
An Action markup object describes the deep link that takes users to the content and the access level required for the content. The object is a property (potentialAction
) of a content markup object.
There are two ways to specify the access restrictions:
- For Watch Actions, use an Action access specification object.
- For Listen Actions, use an offer object.
Action markup template
If the content has multiple deep links, an Action markup object includes multiple target objects. For instance, the content's deep link for iOS may be different from the Android deep link. Also, if there are different access restrictions based on the regions and periods of time, an Action markup object can have multiple Action access specification objects, or offer objects, as shown in the templates below.
Action markup object template for Watch Actions:
"potentialAction": {
"@type": "WatchAction",
"target": [
{ <TARGET OBJECT 01> },
{ <TARGET OBJECT 02> }
],
"actionAccessibilityRequirement": [
{ <ACTION ACCESSIBILITY OBJECT 01> },
{ <ACTION ACCESSIBILITY OBJECT 02> }
]
}
Action markup object template for Listen Actions:
"potentialAction": {
"@type": "ListenAction",
"target": [
{ <TARGET OBJECT 01> },
{ <TARGET OBJECT 02> }
],
"expectsAcceptanceOf": [
{ <OFFER OBJECT 01> },
{ <OFFER OBJECT 02> }
]
}
Target
A target object provides the mapping of a deep link to various Google platforms. The object is a property (target
) of an Action markup object.
Target example
If the content has multiple deep links based on the platforms, create multiple target objects to provide different mappings. For instance, the content's deep link for Chromecast may be different from the other platforms' deep links, as shown in the example below.
Example of a target object (basic):
"target": {
"@type": "EntryPoint",
"urlTemplate": "http://www.example.com/my_favorite_movie?autoplay=true",
"actionPlatform": [
"http://schema.org/DesktopWebPlatform",
"http://schema.org/MobileWebPlatform",
"http://schema.org/AndroidPlatform",
"http://schema.org/IOSPlatform",
"http://schema.googleapis.com/GoogleVideoCast"
]
}
Target object example with two deep links:
"target": [
{
"@type": "EntryPoint",
"urlTemplate": "http://www.example.com/my_favorite_movie?autoplay=true",
"actionPlatform": [
"http://schema.org/DesktopWebPlatform",
"http://schema.org/MobileWebPlatform",
"http://schema.org/AndroidPlatform",
"http://schema.org/IOSPlatform"
]
},
{
"@type": "EntryPoint",
"urlTemplate": "http://www.example.com/cast/my_favorite_movie?autoplay=true",
"actionPlatform": [
"http://schema.googleapis.com/GoogleVideoCast"
]
}
]
Action access specification
An Action access specification object describes the access requirement for the content based on the region and period of time. The object is a property (actionAccessibilityRequirement
) of an Action markup object.
The object's category
can be nologinrequired
, free
, subscription
, externalsubscription
, rental
, or purchase
.
- If
category
issubscription
orexternalsubscription
, you need a Media subscription object to describe the details of the subscription.- If the content requires an additional purchase for the subscribers, you need to use an offer object to specify the price.
- If
category
isrental
orpurchase
, you need to use an offer object to specify the price.
Action access requirement examples
Free
No login required
The content is available without login or subscription.
{
"actionAccessibilityRequirement": {
"@type": "ActionAccessSpecification",
"category": "nologinrequired",
"availabilityStarts": "2015-01-01T00:00Z",
"availabilityEnds": "2015-12-31T00:00Z",
"eligibleRegion": {
"@type": "Country",
"name": "US"
}
}
}
- Set
category
tonologinrequired
. - Don't include
expectAcceptanceOf
.
Login required
The content requires to users to be logged in but doesn't require a subscription.
{
"actionAccessibilityRequirement": {
"@type": "ActionAccessSpecification",
"category": "free",
"availabilityStarts": "2015-01-01T00:00Z",
"availabilityEnds": "2015-12-31T00:00Z",
"eligibleRegion": {
"@type": "Country",
"name": "US"
}
}
}
- Set
category
tofree
. - Don't include
expectAcceptanceOf
.
Single Subscription
No additional cost
The content is available to the subscribers without additional cost.
{
"actionAccessibilityRequirement": {
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2015-01-01T00:00Z",
"availabilityEnds": "2015-12-31T00:00Z",
"eligibleRegion": {
"@type": "Country",
"name": "US"
}
}
}
- Don't include
expectAcceptanceOf
inactionAccessibilityRequirement
; the lack of this property indicates that there is no additional charge for the content.
Additional cost
The content is available to the subscribers but requires an additional cost.
{
"actionAccessibilityRequirement": {
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2015-01-01T00:00Z",
"availabilityEnds": "2015-12-31T00:00Z",
"eligibleRegion": {
"@type": "Country",
"name": "US"
},
"expectsAcceptanceOf": {
"@type": "Offer",
"price": 4.99,
"priceCurrency": "USD"
}
}
}
- Use
expectAcceptanceOf
inactionAccessibilityRequirement
to indicate that the content requires an additional charge for the subscribers.
Multi-tiered Subscription
No additional cost
The content is available to the subscribers 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",
"name": "Basic Package",
"@id": "[partner determined string]",
"identifier": "example.com:basic"
},
{
"@type": "MediaSubscription",
"name": "Premium Package",
"@id": "[partner determined string]",
"identifier": "example.com:premium"
}
]
}
}
- Use
requiresSubscription
to indicate that your platform has multiple subscription offerings - Add multiple items in
requiresSubscription
to indicate that the content is available through different subscriptions. - Don't include
expectAcceptanceOf
inactionAccessibilityRequirement
; the lack of this property indicates that there is no additional charge for the content. - The requiresSubscription.identifier property and an entitlement API are required in this case. See Entitlement API Requirements
Additional cost
The content is available to the subscribers but requires 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",
"name": "Basic Package",
"@id": "[partner determined string]"
},
{
"@type": "MediaSubscription",
"name": "Premium Package",
"@id": "partner determined string]"
}
],
"expectsAcceptanceOf": {
"@type": "Offer",
"price": 4.99,
"priceCurrency": "USD"
}
}
}
- Use
requiresSubscription
to indicate that your platform has multiple subscription offerings - Add multiple items in
requiresSubscription
to indicate that the content is available through different subscriptions. - Include
expectAcceptanceOf
inactionAccessibilityRequirement
to indicate that the content requires an additional charge for the subscribers.
Third-Party Subscription
Third-party subscription
The content is available to the subscribers from a different service.
{
"actionAccessibilityRequirement": {
"@type": "ActionAccessSpecification",
"category": "externalsubscription"
"availabilityStarts": "2015-01-01T00:00Z",
"availabilityEnds": "2015-12-31T00:00Z",
"eligibleRegion": {
"@type": "Country",
"name": "US"
}
}
}
- Add
authenticator
to indicate that a different service authenticates the subscribers; for example, HBO GO requires a subscription from the cable provider.
One-Time Purchase
Purchase
The content is available for an indefinite amount of time after 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/"
}
}
}
}
- Set
category
topurchase
. - Include
expectAcceptanceOf
inactionAccessibilityRequirement
to indicate the price of the purchase.
Rental
The content is available for an finite amount of time after purchase.
{
"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/"
}
}
}
}
- Set
category
torental
. - Include
expectAcceptanceOf
inactionAccessibilityRequirement
to indicate the price of the rental.
Media subscription
A media subscription object describes the details of the subscription required for content. The object is a property (requiresSubscription
) of an Action access specification object. This is required if actionAccessibilityRequirement.category is subscription or externalSubscription and your subscription offering includes multiple packages or tiers or has add-on support. Do not include this if your subscription is one tiered and gives access to all content in your catalog
Media subscription example
Example of a media subscription object:
"requiresSubscription": {
"@type": "MediaSubscription",
"@id": "http://www.example.com/premium_subscription",
"name": "Example Premium",
"sameAs": "http://www.example.com/premium_subscription"
}
Offer
An offer object describes the price associated with content. The object is a property (expectsAcceptanceOf
) of the following objects:
- For Watch Actions, an Action access specification object.
- For Listen Actions, an Action markup object.
Offer example
Watch Actions specify the expectsAcceptanceOf
property in the Action access specification object:
"potentialAction":{
"@type":"WatchAction",
"target":{
"@type":"EntryPoint",
"urlTemplate":"http://www.example.com/my_favorite_movie?autoplay=true",
"actionPlatform":[ "http://schema.org/DesktopWebPlatform" ]
},
"actionAccessibilityRequirement": {
"@type": "ActionAccessSpecification",
"category": "purchase",
"availabilityStarts": "2019-01-01T00:00Z",
"availabilityEnds": "2019-12-31T00:00Z",
"eligibleRegion": {
"@type": "Country",
"name": "US"
},
"expectsAcceptanceOf": {
"@type": "Offer",
"price": 7.99,
"priceCurrency": "USD",
"seller": {
"@type": "Organization",
"name": "My example seller"
}
}
}
}
Listen Actions specify the expectsAcceptanceOf
property directly in the Action markup object:
"potentialAction":{
"@type":"ListenAction",
"target":{
"@type":"EntryPoint",
"urlTemplate":"http://www.example.com/playlist/top_pop_songs?autoplay=true",
"actionPlatform":[ "http://schema.org/DesktopWebPlatform" ]
},
"expectsAcceptanceOf":{
"@type": "Offer",
"eligibleRegion": {
"@type":"Country",
"name":"US"
},
"category": "subscription",
"name": "Example Music",
"price": 9.99,
"priceCurrency": "USD",
"seller": {
"@type": "Organization",
"name": "My example seller",
"sameAs": "http://www.example.com"
}
}
}
Image
An image object describes the image associated with content.
The requirements for the image are the following:
- For Watch Actions, provide a high-resolution image (minimum of 140x210 pixels) with a 2:3 aspect ratio.
- The image must be in
.jpg
or.png
format.
- The image must be in
- For Listen Actions, provide a high-resolution image (minimum of 300x300 pixels) with a 1x1 aspect ratio.
- We recommend 600x600 pixels or higher.
- The image must be in
.jpg
,.png
, or.gif
format.
- The image's URL must be crawlable and indexable.
- You must have rights to use the image and allow the image to be shown on Google devices and properties.
- The image must not contain the following:
- Blurry, pixelated, rotated, or poor quality image.
- Unlicensed or stock photography.
- Nudity.
- Illegal content.
- When you update
MusicPlaylist
, update its image to reflect the new content.
Image example
"image": {
"@type": "ImageObject",
"contentUrl" : "http://www.example.com/artist/my_favorite_artist/1x1/photo1.jpg",
"dateModified" : "2019-01-05T22:11:33+00:00",
"regionsAllowed" : ["US","UK","MX"]
}
Feed examples
The followng examples display the difference in the feed structure between Watch Actions and Listen Actions.
Watch Actions example
{
"@context": "http://schema.org",
"@type": "DataFeed",
"dateModified": "2018-07-20T00:44:51Z",
"dataFeedElement": [
{
"@context": ["http://schema.org", {"@language": "en"}],
"@type": "Movie",
"@id": "http://www.example.com/my_favorite_movie",
"url": "http://www.example.com/my_favortie_movie",
"name": "My Favorite Movie",
"potentialAction": {
"@type": "WatchAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "http://www.example.com/my_favorite_movie?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": "2018-07-21T10:35:29Z",
"availabilityEnds": "2019-10-21T10:35:29Z",
"eligibleRegion": [
{
"@type": "Country",
"name": "US"
},
{
"@type": "Country",
"name": "CA"
}
],
}
},
"sameAs": "https://en.wikipedia.org/wiki/my_favorite_movie",
"releasedEvent": {
"@type": "PublicationEvent",
"startDate": "2008-01-20",
"location": {
"@type": "Country",
"name": "US"
}
},
"description": "This is my favorite movie.",
"actor": [
{
"@type": "Person",
"name": "John Doe",
"sameAs": "https://en.wikipedia.org/wiki/John_Doe"
},
{
"@type": "Person",
"name": "Jane Doe",
"sameAs": "https://en.wikipedia.org/wiki/Jane_Doe"
}
],
"identifier": [
{
"@type": "PropertyValue",
"propertyID": "IMDB_ID",
"value": "tt0123456"
}
]
}
]
}
Listen Actions example
{
"@context": "http://schema.org",
"@type": "DataFeed",
"dateModified": "2018-07-20T00:44:51Z",
"dataFeedElement": [
{
"@context":"http://schema.googleapis.com/",
"@type":"MusicGroup",
"@id":"http://www.example.com/artist/my_favorite_artist/",
"url":"http://www.example.com/artist/my_favorite_artist/",
"name":"My Favorite Artist",
"sameAs":"https://en.wikipedia.org/wiki/my_favorite_artist",
"description":"This is my favorite pop music artist.",
"potentialAction": {
"@type":"ListenAction",
"target": {
"@type":"EntryPoint",
"urlTemplate":"http://www.example.com/artist/my_favorite_artist?autoplay=true",
"actionPlatform":[
"http://schema.org/DesktopWebPlatform",
"http://schema.org/IOSPlatform",
"http://schema.org/AndroidPlatform",
"http://schema.googleapis.com/GoogleAudioCast",
"http://schema.googleapis.com/GoogleVideoCast"
]
},
"expectsAcceptanceOf":{
"@type":"Offer",
"category":"subscription",
"eligibleRegion": {
"@type":"Country",
"name":"US"
},
"price": 8.99,
"priceCurrency": "USD"
}
},
"subjectOf": {
"@type":"MusicPlaylist",
"@id":"http://www.example.com/artist_mix/my_favorite_artist/",
"url":"http://www.example.com/artist_mix/my_favorite_artist/",
"name":"My Favorite Artist Mix",
"description":"A mix of music similar to My Favorite Artist",
"potentialAction":{
"@type":"ListenAction",
"target": {
"@type":"EntryPoint",
"urlTemplate":"http://www.example.com/artist_mix/my_favorite_artist?autoplay=true",
"actionPlatform":[
"http://schema.org/DesktopWebPlatform",
"http://schema.org/IOSPlatform",
"http://schema.org/AndroidPlatform",
"http://schema.googleapis.com/GoogleAudioCast",
"http://schema.googleapis.com/GoogleVideoCast"
]
},
"expectsAcceptanceOf":{
"@type":"Offer",
"category":"free",
"eligibleRegion": {
"@type":"Country",
"name":"US"
}
}
}
}
}
]
}