Introducing the Forecasts API — Event-driven forecasts for precise demand planning. Fast, accurate, and easy to run.
Explore Now
LogoLogo
Visit websiteWebAppGet DemoTry for Free
  • Introduction
  • Swagger UI
  • Loop
  • System Status
  • Getting Started
    • API Quickstart
    • Data Science Notebooks
    • PredictHQ Data
      • Data Accuracy
      • Event Categories
        • Attendance-Based Events
        • Non-Attendance-Based Events
        • Unscheduled Events
        • Live TV Events
      • Labels
      • Entities
      • Ranks
        • PHQ Rank
        • Local Rank
        • Aviation Rank
      • Predicted Attendance
      • Predicted End Times
      • Predicted Event Spend
      • Predicted Events
      • Predicted Impact Patterns
    • Guides
      • Geolocation Guides
        • Overview
        • Searching by Location
          • Find Events by Latitude/Longitude and Radius
          • Find Events by Place ID
          • Find Events by IATA Code
          • Find Events by Country Code
          • Find Events by Placekey
          • Working with Location-Based Subscriptions
        • Understanding Place Hierarchies
        • Working with Polygons
        • Join Events using Placekey
      • Date and Time Guides
        • Working with Recurring Events
        • Working with Multi-day and Umbrella Events
        • Working with Dates, Times and Timezones
      • Events API Guides
        • Understanding Relevance Field in Event Results
        • Attendance-Based Events Notebooks
        • Non-Attendance-Based Events Notebooks
        • Severe Weather Events Notebooks
        • Academic Events Notebooks
        • Working with Venues Notebook
      • Features API Guides
        • Increase Accuracy with the Features API
        • Get ML Features
        • Demand Forecasting with Event Features
      • Forecasts API Guides
        • Getting Started with Forecasts API
        • Understanding Forecast Accuracy Metrics
        • Troubleshooting Guide for Forecasts API
      • Live TV Event Guides
        • Find Broadcasts by County Place ID
        • Find Broadcasts by Latitude and Longitude
        • Find all Broadcasts for an Event
        • Find Broadcasts for Specific Sport Types
        • Aggregating Live TV Events
        • Live TV Events Notebooks
      • Beam Guides
        • ML Features by Location
        • ML Features by Group
      • Demand Surge API Guides
        • Demand Surge Notebook
      • Guide to Protecting PredictHQ Data
      • Streamlit Demo Apps
      • Guide to Bulk Export Data via the WebApp
      • Industry-Specific Event Filters
      • Tutorials
        • Filtering and Finding Relevant Events
        • Improving Demand Forecasting Models with Event Features
        • Using Event Data in Power BI
        • Using Event Data in Tableau
        • Connecting to PredictHQ APIs with Microsoft Excel
        • Loading Event Data into a Data Warehouse
        • Displaying Events in a Heatmap Calendar
        • Displaying Events on a Map
    • Tutorials by Use Case
      • Demand Forecasting with ML Models
      • Dynamic Pricing
      • Inventory Management
      • Workforce Optimization
      • Visualization and Insights
  • Integrations
    • Integration Guides
      • Keep Data Updated via API
      • Integrate with Beam
      • Integrate with Loop Links
    • Third-Party Integrations
      • Receive Data via Snowflake
        • Example SQL Queries for Snowflake
        • Snowflake Data Science Guide
          • Snowpark Method Guide
          • SQL Method Guide
      • Receive Data via AWS Data Exchange
        • CSV/Parquet Data Structure for ADX
        • NDJSON Data Structure for ADX
      • Integrate with Databricks
      • Integrate with Tableau
      • Integrate with a Demand Forecast in PowerBI
      • Google Cloud BigQuery
    • PredictHQ SDKs
      • Python SDK
      • Javascript SDK
  • API Reference
    • API Overview
      • Authenticating
      • API Specs
      • Rate Limits
      • Pagination
      • API Changes
      • Attribution
      • Troubleshooting
    • Events
      • Search Events
      • Get Event Counts
    • Broadcasts
      • Search Broadcasts
      • Get Broadcasts Count
    • Features
      • Get ML Features
    • Forecasts
      • Models
        • Create Model
        • Update Model
        • Replace Model
        • Delete Model
        • Search Models
        • Get Model
        • Train Model
      • Demand Data
        • Upload Demand Data
        • Get Demand Data
      • Forecasts
        • Get Forecast
      • Algorithms
        • Get Algorithms
    • Beam
      • Create an Analysis
      • Upload Demand Data
      • Search Analyses
      • Get an Analysis
      • Update an Analysis
      • Partially Update an Analysis
      • Get Correlation Results
      • Get Feature Importance
      • Refresh an Analysis
      • Delete an Analysis
      • Analysis Groups
        • Create an Analysis Group
        • Get an Analysis Group
        • Search Analysis Groups
        • Update an Analysis Group
        • Partially Update an Analysis Group
        • Refresh an Analysis Group
        • Delete an Analysis Group
        • Get Feature Importance for an Analysis Group
    • Demand Surge
      • Get Demand Surges
    • Suggested Radius
      • Get Suggested Radius
    • Saved Locations
      • Create a Saved Location
      • Search Saved Locations
      • Get a Saved Location
      • Search Events for a Saved Location
      • Update a Saved Location
      • Delete a Saved Location
    • Loop
      • Loop Links
        • Create a Loop Link
        • Search Loop Links
        • Get a Loop Link
        • Update a Loop Link
        • Delete a Loop Link
      • Loop Settings
        • Get Loop Settings
        • Update Loop Settings
      • Loop Submissions
        • Search Submitted Events
      • Loop Feedback
        • Search Feedback
    • Places
      • Search Places
      • Get Place Hierarchies
  • WebApp Support
    • WebApp Overview
      • Using the WebApp
      • API Tools
      • Events Search
      • How to Create an API Token
    • Getting Started
      • Can I Give PredictHQ a Go on a Free Trial Basis?
      • How Do I Get in Touch if I Need Help?
      • Using AWS Data Exchange to Access PredictHQ Events Data
      • Using Snowflake to Access PredictHQ Events Data
      • What Happens at the End of My Free Trial?
      • Export Events Data from the WebApp
    • Account Management
      • Managing your Account Settings
      • How Do I Change My Name in My Account?
      • How Do I Change My Password?
      • How Do I Delete My Account?
      • How Do I Invite People Into My Organization?
      • How Do I Log In With My Google or LinkedIn Account?
      • How Do I Update My Email Address?
      • I Signed Up Using My Google/LinkedIn Account, but I Want To Log In With My Own Email
    • API Plans, Pricing & Billing
      • Do I Need To Provide Credit Card Details for the 14-Day Trial?
      • How Do I Cancel My API Subscription?
      • Learn About Our 14-Day Trial
      • What Are the Definitions for "Storing" and "Caching"?
      • What Attribution Do I Have To Give PredictHQ?
      • What Does "Commercial Use" Mean?
      • What Happens If I Go Over My API Plan's Rate Limit?
    • FAQ
      • How Does PredictHQ Support Placekey?
      • Using Power BI and Tableau With PredictHQ Data
      • Can I Download a CSV of Your Data?
      • Can I Suggest a New Event Category?
      • Does PredictHQ Have Historical Event Data?
      • Is There a PredictHQ Mobile App?
      • What Are Labels?
      • What Countries Do You Have School Holidays For?
      • What Do The Different Event Ranks Mean?
      • What Does Event Visibility Window Mean?
      • What Is the Difference Between an Observed Holiday and an Observance?
    • Tools
      • Is PHQ Attendance Available for All Categories?
      • See Event Trends in the WebApp
      • What is Event Trends?
      • Live TV Events
        • What is Live TV Events?
        • Can You Access Live TV Events via the WebApp?
        • How Do I Integrate Live TV Events into Forecasting Models?
      • Labels
        • What Does the Closed-Doors Label Mean?
    • Beam (Relevancy Engine)
      • An Overview of Beam - Relevancy Engine
      • Creating an Analysis in Beam
      • Uploading Your Demand Data to Beam
      • Viewing the List of Analysis in Beam
      • Viewing the Table of Results in Beam
      • Viewing the Category Importance Information in Beam
      • Feature Importance With Beam - Find the ML Features to Use in Your Forecasts
      • Beam Value Quantification
      • Exporting Correlation Data With Beam
      • Getting More Details on a Date on the Beam Graph
      • Grouping Analyses in Beam
      • Using the Beam Graph
      • Viewing the Time Series Impact Analysis in Beam
    • Location Insights
      • An Overview of Location Insights
      • How to Set a Default Location
      • How Do I Add a Location?
      • How Do I Edit a Location?
      • How Do I Share Location Insights With My Team?
      • How Do I View Details for One Location?
      • How Do I View My Saved Locations as a List?
      • Search and View Event Impact in Location Insights
      • What Do Each of the Columns Mean?
      • What Is the Difference Between Center Point & Radius and City, State, Country?
Powered by GitBook

PredictHQ

  • Terms of Service
  • Privacy Policy
  • GitHub

© 2025 PredictHQ Ltd

On this page
  • Coverage
  • Ranking

Was this helpful?

  1. Getting Started
  2. PredictHQ Data
  3. Event Categories

Live TV Events

Live TV Events covers live broadcast sports games with a large number of people watching at a particular time across different counties across the United States.

PreviousUnscheduled EventsNextLabels

Last updated 1 month ago

Was this helpful?

For example, during the basketball game on March 27, 2021, there were over 150,000 people in Cook County, Illinois watching the live broadcast of the basketball game, as well as over 130,000 people were watching the game in Los Angeles County, California, etc.

Note: Live TV Events covers live games. Replays of sporting events are not included.

Live TV events provide viewership data that is attached to events in other categories. Initially, it was launched for the sports category. In future it will be extended to other categories. Live TV events is not actually a category itself but consists of rich information on who is watching events in different locations.

The current release of Live TV events shows the number of people watching sports events per county in the US.

Live TV events include live streaming and broadcast TV games (such as MLS Soccer games streamed on Apple TV).

Coverage

Event Types

We have two different types of broadcast information. Major sports league viewership uses one model and top viewership sports uses a different approach. This affects how the viewership is calculated and which counties viewership is shown in. For the major sports leagues, viewership per county uses TV schedule information to predict where people will watch a game. Viewership is only shown for the counties where we predict people will watch a game. Top viewership sports, unlike the major sports leagues games, will always show viewership in all counties in the US.

7 MAJOR SPORTS LEAGUES

All televised sports games from the following 7 sports leagues are covered in our live TV events, the broadcasts may have status of either scheduled or cancelled:

NFL, NBA, NHL, MLB, MLS, D1 NCAA Basketball, D1 NCAA Football

TOP VIEWERSHIP SPORTS

Live TV Events extends coverage to some popular sports games beyond the above seven leagues. These are events that have high viewership and are assumed to be televised nationally (in all counties). The broadcasts may have status of either predicted or cancelled

Top viewership sports are typically one-off events or are finals of their respective competitions, such as the 2019 NCAA Women's Basketball Final:

SPORTS TYPE
SPORTS LEAGUE
EVENT TYPE

auto-racing

  • nascar

  • indy-car

  • NASCAR Cup Series Races

  • Indy 500

horse-racing

  • kentucky-derby

  • preakness-stakes

  • belmont-stakes

  • Kentucky Derby Horse Racing

  • Preakness Stakes Horse Racing

  • Belmont Stakes Horse Racing

basketball

  • ncaa-women

NCAA Women's Basketball Division 1 Tournament Semifinals and Finals

baseball

  • ncaa

NCAA Baseball World Series Finals

softball

  • ncaa-women

NCAA Softball World Series Finals

boxing

  • boxing

Popular boxing games, for example Premier Boxing Champions

mma

  • ufc

Popular UFC games, for example UFC 246

tennis

  • wimbledon

  • us-open

Men’s and Women’s Singles Finals

golf

  • masters

  • pga-championship

  • us-open

  • pga-tour

  • Augusta Masters all days of competition

  • PGA Championship all days of competition

  • USA Open all days of competition

  • Arnold Palmer weekend days of competition

  • Genesis Invitational weekend days of competition

  • Pebble Beach weekend days of competition

  • BMW Championship weekend days of competition

  • Farmers Insurance weekend days of competition

soccer

  • fifa-world-cup-women

  • fifa-world-cup

  • uefa-champions-league

  • concacaf-champions-league

  • concacaf-gold-cup

  • copa-america

  • FIFA World Cup Semis onward

  • UEFA Champions League Final

  • CONCACAF Champions League Final

  • CONCACAF Gold Cup Final

  • Copa America Final

  • UWNST World Cup Playoff matches

Note: The sports type column is shown in the event_label field in the broadcast record.

Date Range Coverage

Live TV Events via the Broadcast API covers sports games that started from November 1, 2021, to 90 days in the future (90 days from the current date).

Location

Live TV Events are currently available in the US at the current stage.

Broadcast Status

Broadcasts have three possible status values:

  • scheduled For those broadcasts where we know the date, time and location of a TV broadcast based on TV schedule information. We enrich our data with television listings to determine their televised time and location (county).

  • predicted For these broadcasts where we predict their televised time and location (county). It means we don’t have detailed TV schedule information for the sports event. These events have high viewership and are assumed to be televised nationally (in all counties), they are typically one-off events or are finals of their respective competitions. We calculate viewership per county based on many factors including the amount of sports fans in different counties. This information is not as precise as those with the scheduled broadcast status but should give a reasonably accurate prediction of who will be watching these large events. Customers may want to use the broadcast_status parameter to indicate the confidence of a broadcast airing; they may build this as a feature or to treat scheduled broadcasts differently from predicted.

  • cancelled The broadcast is no longer scheduled to be televised.

Date & Time

Start date

Yes

Yes

  • Broadcast records have a start date and time in both UTC and local time where the broadcast is scheduled.

  • Physical events have a start date and time in both UTC and local time in the event timezone.

End date

No

Yes

  • The Broadcast record doesn’t have an end date or time available.

  • Physical events have an end date and time in both UTC and local time in the event timezone.

Start time

Yes

Yes

End time

No

Yes

Predicted end time

No

Yes

For sports events where there is no official end time available, we predict end times using our machine learning models and intelligent algorithms. PredictHQ’s Predicted End Times feature provides end times for the physical event in it’s local timezone.

Timezone

Yes

Yes

Location / Geopoint

The broadcast record presents the number of people who are watching the live sports game in a county. The latitude and longitude provided with the broadcast record under the geopoint element references the center of the county. For example, the center of Erie County in New York state shown on the right.

The associated sports event is taking place in a physical location with the latitude and longitude pointing to the specific location. The venue name and address is also attached on the event record.

Ranking

PHQ Viewership

PHQ Viewership is the number of people who watch the live broadcast game in a county. Broadcast records have PHQ Viewership available.

  "geopoint": {
      "lon": -78.77966,
      "lat": 42.75824
  },

Timeframe for broadcasts

The Live TV Events machine learning models predicted the viewership for sports games before they happen. Broadcast records are generated 90 days before a sports game starts. However, viewership is updated daily from 14 days before the event starts providing more accurate data. To get the most accurate data we recommend using the broadcast viewership from 14 days before the event or sooner. The viewership numbers generated between 90 days and 14 days can be used as a high-level less accurate indication of viewership.

Physical Event Details

The broadcast API also returns the physical event details accordingly with all available information. Users don’t need an event subscription to access relevant information.

  • Event ID: event_id of the physical event can be used to find all broadcasts nationwide for that specific sport game.

  • Label: event.label for the physical sports event provides more information about the sports type and league. It can be used to find broadcasts for the specific sports type.

  • Entity: The physical sports events have venue entities available.

  • PHQ Rank: The physical sports events have PHQ Rank available.

  • Local Rank: The physical sports events have Local Rank available.

  • PHQ Attendance: The physical sports events have PHQ Attendance available.

{
    "count": 1,
    "next": null,
    "previous": null,
    "overflow": false,
    "results": [
        {
            "broadcast_id": "u5aCvebffuNFpGSGNQFiU4",
            "updated": "2020-11-30T06:58:28Z",
            "first_seen": "2020-11-26T01:29:23Z",
            "dates": {
                "start": "2020-02-02T23:30:00Z",
                "start_local": "2020-02-02T15:30:00",
                "timezone": "America/Los_Angeles"
            },
            "location": {
                "geopoint": {
                    "lon": -122.4425,
                    "lat": 37.77823
                },
                "place_hierarchies": [
                    ["6295630","6255149","6252001","5332921","5391997"]
                ],
                "places": [
                    {
                        "place_id": "5391997",
                        "type": "county",
                        "name": "San Francisco County",
                        "county": "City and County of San Francisco",
                        "region": "California",
                        "country": "US"
                    }
                ],
                "country": "US"
            },
            "phq_viewership": 300609,
            "record_status": "active",
            "broadcast_status": "scheduled",
            "event": {
                "event_id": "svbfg9xT4YSVUeeAKp",
                "title": "Super Bowl - 49ers vs Kansas City Chiefs",
                "category": "sports",
                "labels": [
                    "american-football",
                    "nfl",
                    "sport"
                ],
                "dates": {
                    "start": "2020-02-02T23:30:00Z",
                    "end": "2020-02-03T03:11:00Z",
                    "start_local": "2020-02-02T18:30:00",
                    "end_local": "2020-02-02T22:11:00",
                    "predicted_end_local": "2020-02-02T21:25:00",
                    "timezone": "America/New_York"
                },
                "location": {
                    "geopoint": {
                        "lon": -80.23886040000002,
                        "lat": 25.9579665
                    },
                    "place_hierarchies": [
                        ["6295630","6255149","6252001","4155751","4164238","4161298"],
                        ["6295630","6255149","6252001","4155751","4149007","4155966"]
                    ],
                    "country": "US"
                },
                "entities": [
                    {
                        "entity_id": "wVgG7p8ZKRKEPPrNDq4my9",
                        "type": "venue",
                        "name": "Hard Rock Stadium",
                        "formatted_address": "347 Don Shula Dr\nMiami Gardens, FL 33056\nUnited States of America"
                    }
                ],
                "phq_attendance": 65326,
                "phq_rank": 86,
                "local_rank": 100,
                "aviation_rank": 99
            }
        }
    ]
}

Places in any can be used to search in the API or in our WebApp. The results will be returned on the county level where the place is located. For example, users can search for the broadcast in Bell City, Los Angeles, and all broadcasts in Los Angeles County that match other criteria will be returned in the result.

Villanova Wildcats vs Baylor Bears
hierarchy level