Content markup properties of live TV channels

This section provides the details of the content markup properties for the BroadcastService, CableOrSatelliteService, TelevisionChannel, Organization entity types. To better understand the relationship between these types, review the LiveTV Channels concepts.

BroadcastService Specification table

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
  • Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
@type Text Required - Always set to BroadcastService.
@id URL Required - The content's identifier in URI format; for example, https://example.com/1234abc.
@id must meet the following requirements:
  • Globally unique across your catalog
  • Static; The ID should be stable and not change over time (even if the url property of the show changes). It will be treated as an opaque string and does not have to be a working link.
  • In the form of Unified Resource Identifier (URI)
  • The domain used for the @id value must be owned by your organization.
Because an entity's url meets all the requirements as an identifier, we recommend you use an entity's url as @id. See the Identifier section for more details.
url URL Required if applicable - The canonical URL of the broadcast service if the channel is available to view on the Internet. It is optional for a service delivered on cable/satellite/over the air. Google uses this URL to match the content in your feed to the content in Google's databases.
url must meet the following requirements:
  • url must be globally unique
  • url must contain a working canonical URL that Google can crawl.
For playback's deep link, see the target object's urlTemplate property instead.
name Text Required - The name of the network.
  • Use an array to list the names in different languages. See the Multiple regions and languages example.
  • Note that only one name is supported per locale (language-country pair).
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.
callSign Text The official government-issued callsign of the broadcast service.
inLanguage Text or Language Highly Recommended Why? The primary broadcast language of the channel. Please use one of the language codes from the IETF BCP 47 standard.
category Text Highly Recommended Why? A category for the item. Greater signs or slashes can be used to informally indicate a category hierarchy. e.g Sports, Sports > Football, News, Movie, Music, Documentary.`
contentRating Text or Rating Required for an adult only TV broadcast service - Most restrictive rating for the content broadcast on the channel. If the content rating is given in the form of a Text string, the rating agency needs to be prepended to the rating with whitespace in between; for example, a "TV-Y" rating from agency "TVPG" in the U.S. is described as "TVPG TV-Y". See the list of agencies.
contentRating.author Organization Required if contentRating uses Rating - The name of the rating agency.
contentRating.ratingValue Text Required if contentRating uses Rating - The value of the rating.
contentRating.advisoryCode Text The advisory code for the content. Accepted values include D, FV, L, S, and V. D = Dialogue, FV = Fantasy Violence , L = Language, S = Sexual Content, V = Violence.
description Text A description of the broadcast service. 300-character limit. Use an array to provide the descriptions in multiple languages and/or in different lengths.
slogan Text A slogan of the broadcast service.
areaServed Country, State, City, or GeoShape Required if applicable - This is required if the channel switch is fulfilled by TV service provider - The area in which users can expect to receive the broadcast service. Use the ISO 3166-1 country code to specify countries.
  • Use an array to represent multiple areas.
  • Do not mix Country, State, City with GeoShape.
  • logo ImageObject Required if integrating with GoogleTV. Highly Recommended otherwise Why? An image that represents this broadcast service.
    • GoogleTV integrations require one logo that can be used on a dark background. It should have a transparent background with a colored or white logo, one that is clearly visible on a dark background.
    • Image for logo should adhere to 1:1 or 4:3 or 16:9 aspect ratio (in that order of preference) and should have a resolution of 80x80px or greater.
    • Use the forDarkBackground value for the custom property name contentAttributes as part of the additionalProperty property to indicate the type of background on which the logo should be used.
    • Padding in either length or width (but not both) is acceptable if added to maintain the aspect ratio.
    • See the Image section for other requirements and specifications.
    See example below
    potentialAction WatchAction Required if applicable - An Action markup object that provides the details of the action. See the Action markup properties for details.
    videoFormat Text The highest quality definition supported on this broadcast service; for example,
    • "SD" for standard-definition.
    • "HD" for high-definition.
    • "2K" for 2K resolution.
    • "4K" for 4K resolution.
    • "8K" for 8K resolution.
    broadcastTimezone Text The timezone of this broadcast service in IANA format; for example, America/Los_Angeles. Use an array for multiple timezones.
    broadcastAffiliateOf Organization Required - The TV network that provides programming for this broadcast service or the organization that this broadcast service belongs to.
    broadcastAffiliateOf.@id Text Required - Set to @id of the TV network.
    broadcastAffiliateOf.@type Text Required - Always set to Organization.
    identifier PropertyValue Highly Recommended Why? - External or other ID that identifies this entity, such as _PARTNER_ID_. Multiple identifiers are allowed. See the Identifier properties section for details.
    popularityScore PopularityScoreSpecification Highly Recommended Why? A score that Google uses, plus other signals, to determine which media to play for users. This score represents the popularity of the content in relation to other content in your catalog; therefore, the score's scale needs to be consistent across your feeds, among all the entities in your catalog. By default, an entity's popularity score is set to 0.
    popularityScore.@type Text Always set to PopularityScoreSpecification.
    popularityScore.value Number A non-negative numeric value that indicates the popularity of the entity; a higher score means higher popularity.
    popularityScore.eligibleRegion Country Region(s) where this popularity score is applicable. If the popularity score is globally applicable, set to EARTH. By default, this property is set to EARTH.
    Note: Locale-specific popularity takes precedence over global (EARTH) popularity

    BroadcastService Example

    {
        "@context": [
            "http://schema.org",
            {
                "@language": "en"
            }
        ],
        "@type": "BroadcastService",
        "@id": "http://example.com/stations/example-tv",
        "name": "EXAMPLE-TV",
        "broadcastDisplayName": "ABCD",
        "url": "http://example.com/stations/example-tv",
        "callSign": "EXA-TV",
        "videoFormat": "SD",
        "inLanguage": "en",
        "broadcastTimezone": "America/Los_Angeles",
        "broadcastAffiliateOf": {
            "@type": "Organization",
            "@id": "http://example.com/networks/abcd-network"
        },
        "identifier": [
            {
                "@type": "PropertyValue",
                "propertyID": "TMS_ID",
                "value": "12258"
            },
            {
                "@type": "PropertyValue",
                "propertyID": "_PARTNER_ID_",
                "value": "exampletv-123456"
            }
        ],
        "popularityScore": {
            "@type": "PopularityScoreSpecification",
            "value": 178,
            "eligibleRegion": [
                {
                    "@type": "Country",
                    "name": "US"
                }
            ]
        },
        "potentialAction": {
            "@type": "WatchAction",
            "target": {
                "@type": "EntryPoint",
                "urlTemplate": "http://example.com/livestream",
                "actionPlatform": [
                    "http://schema.org/DesktopWebPlatform",
                    "http://schema.org/MobileWebPlatform",
                    "http://schema.org/AndroidPlatform",
                    "http://schema.org/IOSPlatform",
                    "http://schema.googleapis.com/GoogleVideoCast",
                    "http://schema.org/AndroidTVPlatform"
                ]
            },
            "actionAccessibilityRequirement": {
                "@type": "ActionAccessSpecification",
                "category": "externalsubscription",
                "availabilityStarts": "2018-07-21T10:35:29Z",
                "availabilityEnds": "2019-10-21T10:35:29Z",
                "requiresSubscription": {
                    "@type": "MediaSubscription",
                    "@id": "http://example.com/subscription",
                    "name": "ABCD",
                    "sameAs": "http://example.com/subscription",
                    "authenticator": {
                        "@type": "Organization",
                        "name": "TVE"
                    }
                },
                "eligibleRegion": [
                    {
                        "@type": "Country",
                        "name": "US"
                    }
                ]
            }
        },
        "logo": [
            {
                "@context": "http://schema.org",
                "@type": "ImageObject",
                "name": "Example Logo Light",
                "contentUrl": "http://example.com/images/example-logo-light.jpg",
                "additionalProperty": [
                    {
                        "@type": "PropertyValue",
                        "name": "contentAttributes",
                        "value": [
                            "forLightBackground"
                        ]
                    }
                ]
            },
            {
                "@context": "http://schema.org",
                "@type": "ImageObject",
                "name": "Example Logo Dark",
                "contentUrl": "http://example.com/images/example-logo-dark.jpg",
                "additionalProperty": [
                    {
                        "@type": "PropertyValue",
                        "name": "contentAttributes",
                        "value": [
                            "forDarkBackground"
                        ]
                    }
                ]
            }
        ]
    }
    

    CableOrSatelliteService specification table

    Property Expected Type Description
    @context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
    • Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
    @type Text Required - Always set to CableOrSatelliteService.
    @id URL Required - The content's identifier in URI format; for example, https://example.com/1234abc.
    @id must meet the following requirements:
    • Globally unique across your catalog
    • Static
    • In the form of Unified Resource Identifier (URI)
    Because an entity's url meets all the requirements as an identifier, we recommend you use an entity's url as @id. See the Identifier section for more details.
    name Text Required - The name of the TV service.
    • Use an array to list the names in different languages. See the Multiple regions and languages example.
    • Note that only one name is supported per locale (language-country pair).
    areaServed Country, State, City, or GeoShape Required - The area in which users can expect to receive the broadcast service.
    provider Organization Required - The parent provider of the service, if applicable. For example, ExampleTV is the provider of its regional services ExampleTV San Francisco and ExampleTV San Diego.
    provider.@id Text Required - The ID of the TV operator.
    provider.@type Text Required - Always set to Organization.
    identifier PropertyValue Highly Recommended Why? - External or other ID that identifies this entity, such as a Gracenote TMS ID for this broadcast service. Multiple identifiers are allowed. See the Identifier properties section for details.

    CableOrSatelliteService examples

    Example of a cable or satellite service:

    {
      "@context":["http://schema.org", {"@language": "en"}],
      "@type":"CableOrSatelliteService",
      "@id":"http://example.com/provider-lineups/exampletv-san-francisco",
      "name":"ExampleTV San Francisco",
      "provider": {
        "@type": "Organization",
        "@id": "http://example.com/providers/exampletv"
      },
      "areaServed":[
        {
          "@type":"GeoShape",
          "@id": "http://example.com/area1"
        }
      ],
      "identifier": {
        "@type": "PropertyValue",
        "propertyID": "TMS_ID",
        "value": "12345"
      }
    }
    
    {
      "@type": "GeoShape",
      "@id": "http://example.com/area1",
      "addressCountry": "US",
      "postalCode": [
        "94118",
        "94119"
      ]
    }
    

    Example of a Virtual Multichannel Video Programming Distributor (vMVPD):

    {
      "@context":["http://schema.org", {"@language": "en"}],
      "@type":"CableOrSatelliteService",
      "@id":"http://example.com/providers/my-online-example-tv",
      "name":"My Online Example TV",
      "provider": {
        "@type": "Organization",
        "@id": "http://my-online-tv.com"
      },
      "areaServed":[
        {
          "@type":"Country",
          "name": "US",
        },
        {
          "@type":"Country",
          "name": "CA",
        }
      ]
    }
    

    TelevisionChannel specification table

    Property Expected Type Description
    @context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
    • Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
    @type Text Required - Always set to TelevisionChannel.
    @id URL Required - The content's identifier in URI format; for example, https://example.com/1234abc.
    @id must meet the following requirements:
    • Globally unique across your catalog
    • Static
    • In the form of Unified Resource Identifier (URI)
    Because an entity's url meets all the requirements as an identifier, we recommend you use an entity's url as @id. See the Identifier section for more details.
    broadcastChannelId Text Required - A unique identifier by which this BroadcastService can be identified as a cable, satellite, or Internet TV service.
    • In the US, this is typically a number for cable or satellite TV.
    • For an Internet TV service (for example, a vMVPD), provide the channel name.
    channelOrder Number Required for GoogleTV, optional otherwise - Use this property to indicate the order in which the channels should be displayed in the electronic programming guide for Google TV integrations.

    The channelOrder should be unique across the channels in the feed and should ideally start from 1. channelOrder cannot have a negative or 0 value.
    broadcastServiceTier Text Use the following values:
    • Free for the channel that do not require subscriptions.
    • Standard for the channels included with a basic subscription.
    • Premium for the channels that require a payment on top of the basic subscription.
    Use an array to provide multiple values.
    inBroadcastLineup CableOrSatelliteService Required - The @id of the CableOrSatelliteService that provides this channel to the viewers.
    providesBroadcastService BroadcastService Required - The @id of the BroadcastService whose programming this channel provides.

    TelevisionChannel examples

    Example of a cable or satellite TV channel:

    {
      "@context":["http://schema.org", {"@language": "en"}],
      "@type":"TelevisionChannel",
      "@id":"http://example.com/channels/exampleTV/example-tv-7",
      "broadcastChannelId":"7",
      "channelOrder": 1,
      "broadcastServiceTier":["Premium", "Standard"],
      "inBroadcastLineup":{
        "@type":"CableOrSatelliteService",
        "@id":"http://example.com/providers/exampleTV-san-francisco"
      },
      "providesBroadcastService":{
        "@type":"BroadcastService",
        "@id":"http://example.com/stations/example-tv"
      }
    }
    

    Example for an online TV channel:

    {
      "@context":["http://schema.org", {"@language": "en"}],
      "@type":"TelevisionChannel",
      "@id":"http://example.com/channels/my-online-example-tv/sport-channel",
      "broadcastChannelId":"sport-channel",
      "channelOrder": 3,
      "broadcastServiceTier":"Premium",
      "inBroadcastLineup":{
        "@type":"CableOrSatelliteService",
        "@id":"http://example.com/providers/my-online-example-tv"
      },
      "providesBroadcastService":{
        "@type":"BroadcastService",
        "@id":"http://example.com/stations/sport-channel"
      }
    }
    

    Organization specification table

    Property Expected Type Description
    @context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
    • Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
    @type Text Required - Always set to Organization.
    @id URL Required - The content's identifier in URI format; for example, https://example.com/1234abc.
    @id must meet the following requirements:
    • Globally unique across your catalog
    • Static
    • In the form of Unified Resource Identifier (URI)
    Because an entity's url meets all the requirements as an identifier, we recommend you use an entity's url as @id. See the Identifier section for more details.
    name Text Required - The name of the TV network, TV content provider, or TV operator.
    • Use an array to list the names in different languages. See the Multiple regions and languages example.
    • Note that only one name is supported per locale (language-country pair).
    description Text A description of the organization. 300-character limit. Use an array to provide the descriptions in multiple languages and/or in different lengths.
    sameAs URL Highly Recommended Why? A URL to a Wikipedia page that can identify the TV network. This must be distinct from the url property. Only populate with Wikipedia page that talks about a single channel/network entity. Note that Wikipedia pages might use terminology "channel".
    potentialAction WatchAction Required if applicable - This is required if you have multiple channels (BroadcastService) referring to the Organization. An Action markup object that provides the details of the action. See the Action markup properties for details.
    url URL The URL of the organization. Google uses this URL to accurately reconcile this organization with the organization in Google's databases.
    identifier PropertyValue Highly Recommended Why? - External or other ID that identifies this entity, such as a TMS ID for this organization. Multiple identifiers are allowed. See the Identifier properties section for details.
    popularityScore PopularityScoreSpecification Highly Recommended Why? A score that Google uses, plus other signals, to determine which media to play for users. This score represents the popularity of the content in relation to other content in your catalog; therefore, the score's scale needs to be consistent across your feeds, among all the entities in your catalog. By default, an entity's popularity score is set to 0.
    popularityScore.@type Text Always set to PopularityScoreSpecification.
    popularityScore.value Number A non-negative numeric value that indicates the popularity of the entity; a higher score means higher popularity.
    popularityScore.eligibleRegion Country Region(s) where this popularity score is applicable. If the popularity score is globally applicable, set to EARTH. By default, this property is set to EARTH.
    Note: Locale-specific popularity takes precedence over global (EARTH) popularity

    Organization example

    {
      "@context":["http://schema.org", {"@language": "en"}],
      "@type":"Organization",
      "@id":"http://example.com/networks/abcd-network",
      "name":"ABCD",
      "identifier": [
        {
          "@type": "PropertyValue",
          "propertyID": "TMS_ID",
          "value": "12345"
        },
        {
          "@type": "PropertyValue",
          "propertyID": "_PARTNER_ID_",
          "value": "exampletv-12345"
        }
      ],
      "potentialAction": {
        "@type": "WatchAction",
        "target": {
          "@type": "EntryPoint",
          "urlTemplate": "http://example.com/networkstream",
          "actionPlatform": [
            "http://schema.org/DesktopWebPlatform",
            "http://schema.org/MobileWebPlatform",
            "http://schema.org/AndroidPlatform",
            "http://schema.org/IOSPlatform",
            "http://schema.googleapis.com/GoogleVideoCast",
            "http://schema.org/AndroidTVPlatform"
          ]
        },
        "actionAccessibilityRequirement": {
          "@type": "ActionAccessSpecification",
          "category": "externalsubscription",
          "availabilityStarts": "2018-07-21T10:35:29Z",
          "availabilityEnds": "2050-10-21T10:35:29Z",
          "requiresSubscription": {
            "@type": "MediaSubscription",
            "@id": "http://example.com/subscription",
            "name": "ABCD",
            "sameAs": "http://example.com/subscription",
          },
          "eligibleRegion": [
            {
              "@type": "Country",
              "name": "US"
            }
          ]
        }
      },
      "popularityScore": {
        "@type": "PopularityScoreSpecification",
        "value": 178,
        "eligibleRegion": [
          {
            "@type": "Country",
            "name": "US"
          }
        ]
      }
    }
    

    Check out the following pages for the topics related to these properties: