SportsEvents - Modelling, Best Practices and Sample Feed

  • A SportsEvent entity represents a sports game or a full replay of a sports game.

  • Short form content, clips, and shoulder content are not modeled as a SportsEvent.

  • Modeling a SportsEvent can vary based on whether it's part of a Video on demand catalog, live TV catalog streaming online, or live TV catalog streaming online on a channel.

  • Specific entities like BroadcastEvent, Broadcast, BroadcastService, Organization, TelevisionChannel, and CableOrSatelliteService are required depending on the use case for modeling SportsEvents in live TV contexts.

  • Deep links for SportsEvents in a Video on demand catalog should be provided on the SportsEvent entity, while deep links for live broadcasts without a channel should be on the BroadcastEvent entity, and deep links for live broadcasts on a channel should be on the BroadcastService entity.

Definition

A SportsEvent is an entity type representing a sports game or a full replay of a sports game.

What can be modeled as a SportsEvent? A sports game
What can't be modeled as a SportsEvent?

Any short form or clip content or shoulder content. Here's the list:

  • Random recap or replay short clips
  • Previews of the game
  • Highlights of the game
  • Game bloopers
  • Player interview clips
  • Behind the scene videos
  • Game reviews (user generated or otherwise)
  • Random short clips from the game

How do I handle such shoulder content?

Common Use-cases for SportsEvents

S.No. Description Entities Required
Case 1

I need to model a SportsEvent that's part of my live TV catalog and streams online.

The game streams over the internet and is not attached to any channel.

SportsEvent representing the game.

BroadcastEvent representing the broadcast of the game.
Case 2 I need to model a SportsEvent that's part of my live TV catalog and is streamed online on a channel.

SportsEvent representing the game.

BroadcastEvent representing the airing of the game.

BroadcastService, Organization, TelevisionChannel, CableOrSatelliteService entities representing the channel and the lineup.
Case 3 Combinations of the preceding two cases. If you combine the earlier use cases, provide all entity types listed in the corresponding "Entities Required" column.

Best practices and insights into a few checks that we do

The following guidelines and quality checks apply when modeling sports events and their broadcasts.

Apply the following rules across all SportsEvent integrations:

  • Place all sports deep links on SportsEvent.potentialAction: Game-level deep links (WatchAction)—for both channel-less livestreams and Video-on-demand replays—must reside exclusively on the SportsEvent entity (SportsEvent.potentialAction). Never place potentialAction on a BroadcastEvent that references a SportsEvent. (For linear channel broadcasts without an event-specific deep link, provide the channel deep link on BroadcastService.potentialAction.) If a game has multiple streams (for example, regional feeds, home or away broadcasts, multiple languages, or separate live and Video-on-demand replay URLs), provide an array of WatchAction objects in SportsEvent.potentialAction.
  • Pre-roll window (availabilityStarts): Set SportsEvent.potentialAction.actionAccessibilityRequirement.availabilityStarts at least 14 days before SportsEvent.startDate (availabilityStarts <= SportsEvent.startDate - 14 days) so upcoming game tiles and tune-in notifications can surface in advance. You don't need to deliver the feed entity 14 days in advance—event data can be delivered closer to game day, as long as the availabilityStarts timestamp is set at least 14 days prior to SportsEvent.startDate.
  • Overtime buffer (availabilityEnds): Set SportsEvent.potentialAction.actionAccessibilityRequirement.availabilityEnds after SportsEvent.endDate with at least a 2 to 3 hour buffer (availabilityEnds >= SportsEvent.endDate + 2 to 3 hours, or through the end of the Video-on-demand replay window) so the deep link doesn't expire during live overtimes or post-game coverage.
  • @id and url requirements:
    • Use distinct @id values: BroadcastEvent.@id must be different from SportsEvent.@id.
    • Omit url: Do not include a url property on BroadcastEvent or SportsEvent entities.
S.No. Entities Required Guidelines
Case 1

I need to model a SportsEvent that's part of my live TV catalog and streams online.

The game streams over the internet and is not attached to any channel.

Entities Required

  • SportsEvent representing the game
  • BroadcastEvent representing the airing of the game

Modeling guidelines

Sub-case 1: The game is only available live (and not as part of the Video on demand catalog)

  • Provide the BroadcastEvent entity to share the schedule of the broadcast, referencing the game with BroadcastEvent.broadcastOfEvent and specifying the broadcast country in BroadcastEvent.location.
  • Provide the livestream deep link on the SportsEvent entity using SportsEvent.potentialAction (configured with the 14-day pre-roll availabilityStarts and 2–3 hour overtime buffer availabilityEnds).
  • Do not provide BroadcastEvent.potentialAction, BroadcastEvent.url, or SportsEvent.url.
  • Do not provide BroadcastEvent.publishedOn because the game streams online without a linear channel.

Sub-case 2: The game is available live and as part of the Video on demand catalog (for example, when full game replays remain available on demand)

  • Provide the BroadcastEvent entity to share the schedule of each broadcast (referencing BroadcastEvent.broadcastOfEvent and specifying BroadcastEvent.location).
  • Consolidate both live and Video-on-demand playback on SportsEvent.potentialAction—either by extending availabilityEnds through the end of the Video-on-demand window if the URL and entitlements are identical, or by providing multiple WatchAction objects in SportsEvent.potentialAction with their respective actionAccessibilityRequirement windows.
  • Do not provide BroadcastEvent.potentialAction, BroadcastEvent.url, SportsEvent.url, or BroadcastEvent.publishedOn.

Quality checks to perform

  • Set BroadcastEvent.isLiveBroadcast to boolean true (unquoted) when the game airs live. Set it to false for a scheduled replay broadcast.
  • For BroadcastEvent entities that aren't live, BroadcastEvent.startDate shouldn't be earlier than SportsEvent.startDate.
  • Include parentOrganization (with a Wikipedia sameAs URL) on both homeTeam and awayTeam.
Case 2

I need to model a SportsEvent that's part of my live TV catalog and streams online on a channel.

Entities Required

  • SportsEvent that represents the game.
  • BroadcastEvent that represents the airing of the game.
  • BroadcastService, Organization, TelevisionChannel, CableOrSatelliteService entities representing the channel and the lineup.

Modeling guidelines

Sub-case 1: The game is only available live on the linear channel (and not as part of the Video on demand catalog)

  • Provide the BroadcastEvent entity to share the schedule of the broadcast, with BroadcastEvent.publishedOn pointing to the BroadcastService entity, BroadcastEvent.broadcastOfEvent pointing to the SportsEvent entity, and BroadcastEvent.location specifying the broadcast country.
  • Provide the BroadcastService, Organization, TelevisionChannel, and CableOrSatelliteService entities to represent the channel and lineup, with the channel deep link on BroadcastService.potentialAction.
  • Never provide BroadcastEvent.potentialAction, BroadcastEvent.url, or SportsEvent.url.
  • If you also support a direct game-specific deep link, provide it on SportsEvent.potentialAction; if playback is only available through the linear channel deep link on BroadcastService.potentialAction, omit SportsEvent.potentialAction.

Sub-case 2: The game is available live on a channel and as part of the Video on demand catalog

  • Provide the BroadcastEvent entity (with publishedOn, broadcastOfEvent, and location) to share the channel broadcast schedule.
  • Provide the BroadcastService, Organization, TelevisionChannel, and CableOrSatelliteService entities, with the channel deep link on BroadcastService.potentialAction.
  • Never provide BroadcastEvent.potentialAction, BroadcastEvent.url, or SportsEvent.url.
  • Provide SportsEvent.potentialAction on the SportsEvent entity for the event-level / Video-on-demand playback window.

Quality checks to perform

  • Set BroadcastEvent.isLiveBroadcast to boolean true (unquoted) when the game is live, and false for a game replay.
  • For BroadcastEvent entities that aren't live, BroadcastEvent.startDate shouldn't be earlier than SportsEvent.startDate.
  • Include parentOrganization (with a Wikipedia sameAs URL) on both homeTeam and awayTeam.

Examples

Case 1: A sports event that's part of a live TV catalog and is streamed online

Broadcast event

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/live_event/basketball/professional/final_game_6",
  "name": "2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "description": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B.",
  "startDate": "2019-09-16T10:00-08:00",
  "endDate": "2019-09-16T13:00-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": true,
  "broadcastOfEvent": {
    "@type": "SportsEvent",
    "@id": "http://example.com/basketball/professional/final_game_6"
  },
  "location": {
    "@type": "Country",
    "name": "US"
  }
}

Sports event

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "SportsEvent",
  "@id": "http://example.com/basketball/professional/final_game_6",
  "name": "2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "sport": "https://en.wikipedia.org/wiki/Basketball",
  "description": {
    "@language": "en",
    "@value": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B."
  },
  "startDate": "2019-09-16T10:00-08:00",
  "endDate": "2019-09-16T13:00-08:00",
  "homeTeam": {
    "@type": "SportsTeam",
    "name": "Team B",
    "sport": "https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization": {
      "@type": "SportsOrganization",
      "name": "Professional Basketball League",
      "sameAs": "https://en.wikipedia.org/wiki/Professional_Basketball_League"
    },
    "athlete": [
      {
        "@type": "Person",
        "name": "John Doe"
      }
    ]
  },
  "awayTeam": {
    "@type": "SportsTeam",
    "name": "Team A",
    "sport": "https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization": {
      "@type": "SportsOrganization",
      "name": "Professional Basketball League",
      "sameAs": "https://en.wikipedia.org/wiki/Professional_Basketball_League"
    },
    "athlete": [
      {
        "@type": "Person",
        "name": "Jane Doe"
      }
    ]
  },
  "location": {
    "@type": "Place",
    "name": "Example Stadium",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "1600 Amphitheatre Pkwy",
      "addressLocality": "Mountain View",
      "addressRegion": "CA",
      "postalCode": "94043",
      "addressCountry": "US"
    }
  },
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value": "EP000194303282"
    }
  ],
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/pbl_finals_game_6?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": "2019-09-01T10:00-08:00",
      "availabilityEnds": "2019-09-16T16:00-08:00",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "name": "Example Package",
        "commonTier": true,
        "@id": "http://www.example.com/example_package"
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  }
}

Case 2: A sports event that's part of a live TV catalog and is streamed online on a channel

Broadcast event

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/live_event/basketball/professional/final_game_6",
  "name": "2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "description": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B.",
  "startDate": "2019-09-16T10:00-08:00",
  "endDate": "2019-09-16T13:00-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": true,
  "publishedOn": {
    "@type": "BroadcastService",
    "@id": "http://example.com/stations/example_tv"
  },
  "broadcastOfEvent": {
    "@type": "SportsEvent",
    "@id": "http://example.com/basketball/professional/final_game_6"
  },
  "location": {
    "@type": "Country",
    "name": "US"
  }
}

Sports event

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "SportsEvent",
  "@id": "http://example.com/basketball/professional/final_game_6",
  "name": "2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "sport": "https://en.wikipedia.org/wiki/Basketball",
  "description": {
    "@language": "en",
    "@value": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B."
  },
  "startDate": "2019-09-16T10:00-08:00",
  "endDate": "2019-09-16T13:00-08:00",
  "homeTeam": {
    "@type": "SportsTeam",
    "name": "Team B",
    "sport": "https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization": {
      "@type": "SportsOrganization",
      "name": "Professional Basketball League",
      "sameAs": "https://en.wikipedia.org/wiki/Professional_Basketball_League"
    },
    "athlete": [
      {
        "@type": "Person",
        "name": "John Doe"
      }
    ]
  },
  "awayTeam": {
    "@type": "SportsTeam",
    "name": "Team A",
    "sport": "https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization": {
      "@type": "SportsOrganization",
      "name": "Professional Basketball League",
      "sameAs": "https://en.wikipedia.org/wiki/Professional_Basketball_League"
    },
    "athlete": [
      {
        "@type": "Person",
        "name": "Jane Doe"
      }
    ]
  },
  "location": {
    "@type": "Place",
    "name": "Example Stadium",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "1600 Amphitheatre Pkwy",
      "addressLocality": "Mountain View",
      "addressRegion": "CA",
      "postalCode": "94043",
      "addressCountry": "US"
    }
  },
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value": "EP000194303282"
    }
  ]
}

BroadcastService, CableOrSatelliteService, TelevisionChannel, and Organization entities as defined in the Live TV Channel section under Concepts.

How do I handle shoulder content?

What qualifies as shoulder content?
  • Random recap or replay short clips
  • Previews of the game
  • Highlights of the game
  • Game bloopers
  • Player interview clips
  • Behind the scene videos
  • Game reviews (user generated or otherwise)
  • Other random short clips from the game
S.No. Use case Modeling guidelines
Case 1 I have shoulder content in my Video on demand catalog.
  • This isn't supported and can't be provided in the feed.
  • ViTA can be used to provide a subset of this content though. Contact your Google representative to learn more about ViTA.
Case 2 I have shoulder content in my live catalog

Sub-case 1: Content is available to stream live on the internet

  • Provide the BroadcastEvent entity to share the schedule of the broadcast.
  • Provide the deep link of the shoulder content using the BroadcastEvent.potentialAction property (this exception applies only to standalone live shoulder content because there is no SportsEvent entity in the feed).
  • Add any associated metadata (to the clip) directly to the BroadcastEvent . For example, images can be added using the BroadcastEvent.image property. Age ratings can be added using the BroadcastEvent.contentRating property.
  • Since this content type isn't a SportsEvent, the feed must not contain a SportsEvent entity. As such, the broadcastOfEvent property on the BroadcastEvent must not be provided.
  • Since it's not tied to a channel, don't provide the publishedOn property on the BroadcastEvent.

Sub-case 2: Content is available to stream live on the internet on a channel

  • The BroadcastEvent entity must be provided to share the schedule of the broadcast.
  • The BroadcastService, Organization, TelevisionChannel , CableOrSatelliteService entities must be provided to represent the channel and the provider lineup.
  • The deep link to the game must simply be the BroadcastService deep link, represented by the BroadcastService.potentialAction property, which must be provided.
  • The BroadcastEvent.potentialAction property must not be provided.
  • Any associated metadata (to the clip) must be directly added to the BroadcastEvent. For example, images can be added using the BroadcastEvent.image property. Age ratings can be added using the BroadcastEvent.contentRating property.
  • Since this content type isn't a SportsEvent, the feed must not contain a SportsEvent entity. As such, the broadcastOfEvent property on the BroadcastEvent must not be provided.
  • Since it's tied to a channel, provide the publishedOn property on the BroadcastEvent.
Case 3 I have shoulder content available as part of both Video on demand and live TV catalog

Given that Video on demand sports shoulder content isn't accepted in the feed today, this is similar to case 2. See the instructions from there.

Commonly Asked Questions

Q: Where can I find the associated specifications for the entities mentioned earlier?

A: You can find the required specifications here.

Overall documentation Link
SportsEvent Link
BroadcastService, Organization, TelevisionChannel , CableOrSatelliteService Link
BroadcastEvent Link

Q: Is there a more detailed document that explains how to model the live TV channels and lineups?

A: Yes, you can find more details in Live TV Channel section under Concepts. Please feel free to request view access if you aren't able to view the document.

Q: Does ViTA support full live games and full game replays as well?

A: ViTA supports metadata on league based full live games and full game replays (in addition to a subset of shoulder content)

  • For partners that already have a functional Media Actions feed with Google or have a Video on demand or live TV offering, Google requires the feed to expand and include the supported SportsEvent types as well.

    • For the short term, the partners can use ViTA for shoulder content ingestion. Support all types of content through the feed should roll out over the long term.

  • For partners that don't have a Video on demand or live TV offering but carry only league based sports and related shoulder content, ViTA is a great option to begin with. Contact your Google representative to learn more about ViTA.