## 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?](https://developers.google.com/actions/media/concepts/sports_events#how-do-i-handle-shoulder-content) |

## Common Use-cases for SportsEvents

> [!NOTE]
> **Note:** Standalone Video-on-demand `SportsEvent` feeds without `BroadcastEvent` entities are not supported. Every `SportsEvent` in your feed must be paired with at least one `BroadcastEvent` representing its broadcast schedule.

| **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.

### Deep link placement and availability windows (`actionAccessibilityRequirement`)

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

> [!NOTE]
> **Note:** Set `"isLiveBroadcast": true` for live game broadcasts as shown in the following example, or `"isLiveBroadcast": false` when scheduling a replay broadcast.

### 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](https://developers.google.com/actions/media/concepts/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](https://support.google.com/vita#topic=11995493) can be used to provide a subset of this content though. Contact your Google representative to learn more about [ViTA](https://support.google.com/vita#topic=11995493). |
| 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](https://developers.google.com/actions/media/reference/data-specification/events-specification#sportsevent_specification_table) |
| `BroadcastService`, `Organization`, `TelevisionChannel `, `CableOrSatelliteService` | [Link](https://developers.google.com/actions/media/reference/data-specification/live-tv/broadcastservice-specification) |
| `BroadcastEvent` | [Link](https://developers.google.com/actions/media/reference/data-specification/live-tv/broadcastevent-specification) |

### 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](https://developers.google.com/actions/media/concepts/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](https://support.google.com/vita#topic=11995493).