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.

Figure 1. The feed structures of Watch Actions and Listen Actions.

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:

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 nologinrequired, free, subscription, externalsubscription, rental, or purchase.

  • If category is subscription or externalsubscription, 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 is rental or purchase, 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 to nologinrequired.
  • 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 to free.
  • 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 in actionAccessibilityRequirement; 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 in actionAccessibilityRequirement 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 in actionAccessibilityRequirement; 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 expectAcceptanceOfin actionAccessibilityRequirement 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 categoryto purchase.
  • Include expectAcceptanceOfin actionAccessibilityRequirementto 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 categoryto rental.
  • Include expectAcceptanceOfin actionAccessibilityRequirementto 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:

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"
            }
          }
        }
      }
    }
  ]
}