Feed structure overview

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:

Data feed envelope object

Content markup object

Action markup object

Target object
Action access specification object

Media subscription object

Offer object

Listen Actions have the following hierarchy:

Data feed envelope object

Content markup object

Action markup object

Target object
Offer object

Content markup object (Entity-seeded Action)

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/AndroidTVPlatform",
    "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/AndroidTVPlatform",
      "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 any of the following:

nologinrequired
free
subscription

To describe the details of the subscription, create a Media subscription object. If the content requires an additional purchase for the subscribers, use an offer object to specify the price.
externalsubscription

To describe the details of the subscription, create a Media subscription object. If the content requires an additional purchase for the subscribers, use an offer object to specify the price.
rental

Use an offer object to specify the price.
purchase

Use an offer object to specify the price.

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.
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_favorite_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/AndroidTVPlatform",
            "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.org/AndroidTVPlatform",
            "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.org/AndroidTVPlatform",
              "http://schema.googleapis.com/GoogleAudioCast",
              "http://schema.googleapis.com/GoogleVideoCast"
            ]
          },
          "expectsAcceptanceOf":{
            "@type":"Offer",
            "category":"free",
            "eligibleRegion": {
              "@type":"Country",
              "name":"US"
            }
          }
        }
      }
    }
  ]
}