# Feed structure overview The Media Actions feed is a JSON object that contains a collection of entities. An entity is a [schema.org](https://schema.org) object that represents an item in your catalog: a TV episode, a TV series, a movie, a song, an album, and more. ![](https://developers.google.com/actions/images/image-media-actions-29.jpg) **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: - [Data feed envelope object](https://developers.google.com/actions/media/reference#data_feed_envelope) - [Content markup object](https://developers.google.com/actions/media/reference#content_markup) - [Action markup object](https://developers.google.com/actions/media/reference#action_markup) - [Target object](https://developers.google.com/actions/media/reference#target) - [Action access specification object](https://developers.google.com/actions/media/reference#action-access-specification) - [Media subscription object](https://developers.google.com/actions/media/reference#media_subscription) - [Offer object](https://developers.google.com/actions/media/reference#offer) | Listen Actions have the following hierarchy: - [Data feed envelope object](https://developers.google.com/actions/media/reference#data_feed_envelope) - [Content markup object](https://developers.google.com/actions/media/reference#content_markup) - [Action markup object](https://developers.google.com/actions/media/reference#action_markup) - [Target object](https://developers.google.com/actions/media/reference#target) - [Offer object](https://developers.google.com/actions/media/reference#offer) - [Content markup object](https://developers.google.com/actions/media/reference#content_markup) (*[Entity-seeded Action](https://developers.google.com/actions/collect-information/entity-types/identify-the-relationships-music)*) | ## 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](https://developers.google.com/actions/media/reference#content_markup) (entities) that represent all the content in your catalog. A data feed envelope supports the following properties: | Property | Type | Description | |---|---|---| | `@context` | [URL](http://schema.org/URL) | **Required** - Set to `http://schema.org` | | `@type` | [Text](http://schema.org/Text) | **Required** - Set to `DataFeed`. | | `dateModified` | [DateTime](http://schema.org/DateTime) | **Required** - The last modified date and time of the feed, in [ISO 8601 format](https://www.iso.org/iso-8601-date-and-time-format.html) (including timezone). | | `dataFeedElement` | [Thing](http://schema.org/Thing) | **Required** - The [entities](https://developers.google.com/actions/media/reference#content_markup) of your media catalog. | ### Data feed envelope template { "@context": "http://schema.org", "@type": "DataFeed", "dateModified": "2018-07-20T00:44:51Z", "dataFeedElement": [ { }, { }, { }, ... ] } ## 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](https://developers.google.com/actions/collect-information/collect-the-id-url-and-name) and helps describe the content via [metadata](https://developers.google.com/actions/collect-information/collect-the-metadata). ### Content markup template A content markup object can have an array of [Action markup objects](https://developers.google.com/actions/media/reference#action_markup), 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 An Action markup object describes the [deep link](https://developers.google.com/actions/collect-information/identify-the-deep-links#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](https://developers.google.com/actions/media/reference#content_markup). There are two ways to specify the access restrictions: - For Watch Actions, use an [Action access specification object](https://developers.google.com/actions/media/reference#action-access-specification). - For Listen Actions, use an [offer object](https://developers.google.com/actions/media/reference#offer). ### Action markup template If the content has multiple deep links, an Action markup object includes multiple [target objects](https://developers.google.com/actions/media/reference#target). 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": [ { }, { } ], "actionAccessibilityRequirement": [ { }, { } ] } Action markup object template for Listen Actions: "potentialAction": { "@type": "ListenAction", "target": [ { }, { } ], "expectsAcceptanceOf": [ { }, { } ] } ## Target A target object provides the mapping of a [deep link](https://developers.google.com/actions/collect-information/identify-the-deep-links#deep_link) to various [Google platforms](https://developers.google.com/actions/collect-information/identify-the-deep-links#platform_types). The object is a property (`target`) of an [Action markup object](https://developers.google.com/actions/media/reference#action_markup). ### 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](https://developers.google.com/actions/media/reference#action_markup). > [!NOTE] > **Note:** An Action access specification object is only used for Watch Actions. For Listen Actions, use the [offer object](https://developers.google.com/actions/media/reference#offer) to describe the access requirement. 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](https://developers.google.com/actions/media/reference#media_subscription). If the content requires an additional purchase for the subscribers, use an [offer object](https://developers.google.com/actions/media/reference#offer) to specify the price. - `externalsubscription` To describe the details of the subscription, create a [Media subscription object](https://developers.google.com/actions/media/reference#media_subscription). If the content requires an additional purchase for the subscribers, use an [offer object](https://developers.google.com/actions/media/reference#offer) to specify the price. - `rental` Use an [offer object](https://developers.google.com/actions/media/reference#offer) to specify the price. - `purchase` Use an [offer object](https://developers.google.com/actions/media/reference#offer) 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](https://developers.google.com/actions/media/reference#action-access-specification). 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. > [!NOTE] > **Note:** A media subscription object is only used for **Watch Actions**. ### 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](https://developers.google.com/actions/media/reference#action-access-specification). - For Listen Actions, an [Action markup object](https://developers.google.com/actions/media/reference#action_markup). ### Offer example Watch Actions specify the `expectsAcceptanceOf` property in the [Action access specification object](https://developers.google.com/actions/media/reference#action-access-specification): "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](https://developers.google.com/actions/media/reference#action_markup): "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](https://support.google.com/webmasters/answer/6065809). - 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" } } } } } ] }