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
  • Request
  • HTTP Request
  • Query Parameters
  • Response
  • Response Fields
  • Examples
  • Guides

Was this helpful?

  1. API Reference
  2. Broadcasts

Search Broadcasts

Search for Live TV broadcasts happening in a location.

PreviousBroadcastsNextGet Broadcasts Count

Last updated 1 month ago

Was this helpful?

Results are limited by your subscription

Please note that you will not receive an error when requesting a date range or location that is outside of your subscription settings.

This is sometimes confused with missing data. If you're not seeing the results you expect to see then please ensure your subscription covers the location or time period you're searching for.

Your subscription settings can be viewed in the .

Request

HTTP Request

GET https://api.predicthq.com/v1/broadcasts/

Query Parameters

Parameter
Description

broadcast_id

Find broadcasts by unique identifier. Multiple values are accepted as a comma-separated list.

E.g. ?broadcast_id=tFk2LbcpzgeuLXw8dKWa3J

broadcast_status

Find broadcasts by broadcast status. Multiple values are accepted as a comma-separated list.

Possible values:

  • scheduled

  • predicted

  • cancelled

E.g. ?broadcast_status=scheduled

event.category

Find broadcasts by their physical event’s category.

Possible values:

  • sports

E.g. ?event.category=sports

event.event_id

E.g. ?event.event_id=svbfg9xT4YSVUeeAKp

event.entity_id

This parameter can be used to filter broadcasts by team, e.g. ?event.entity_id=GduZL2z24phJQni4ktERGw to retrieve the Los Angeles Lakers broadcasts, or by venue, e.g. ?event.entity_id=qSpch2mYLDa4iygkMdMPYu to retrieve the broadcasts related to a physical game happening at the STAPLES center.

E.g. ?event.entity_id=GduZL2z24phJQni4ktERGw

event.label

Find broadcasts by their physical event’s labels. Multiple values are accepted as a comma-separated list.

Where multiple labels are provided, broadcasts which match any of the labels are returned.

Please note that all event labels are lowercase and that the search is case sensitive.

E.g. ?event.label=nfl,nba

first_seen

Find broadcasts by the time they were seen for the first time. Supported suffixes are:

  • gt: greater than.

  • gte: greater than or equal to.

  • lt: less than.

  • lte: less than or equal to.

The format of first_seen times for this parameter is YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

E.g. ?first_seen.gte=2020-11-30

limit

The maximum number of results to return per page. The default limit is 10. The maximum limit is 500.

E.g. ?limit=50

location.place_id

Find broadcasts by their location's place_id. Multiple values are accepted as a comma-separated list.

  • If the place_id of a county is specified, broadcasts in that county will be returned.

  • If the place_id of a state (region) is specified, broadcasts in all the counties within that state will be returned. US states have the place type region.E.g. If you specify location.place_id=5332921 (California), results will contain broadcasts for all counties in California.

  • For places below the county level, broadcasts in the county that the place belongs to will be returned. E.g. If you specify location.place_id=5327684 (Berkeley), results will contain broadcasts for Alameda County; Berkeley is located within Alameda County. Some places below county level do not belong to a county, in this case, you can try using the location.origin param.

E.g. ?location.place_id=5391997,5128594,5379524,5129915

location.origin

Find broadcasts in the county for the provided geopoint (a latitude and longitude coordinate). The format of the geopoint is {latitude},{longitude}.

The Broadcasts API returns broadcasts at the county level. When you specify a geopoint using location.origin the API returns broadcasts for the county the specified geopoint is within.

If you specify a geopoint within Los Angeles County then broadcasts for Los Angeles County will be returned.

E.g. ?location.origin=40.730610,-73.935242

offset

The number of results to skip.

The default is 0.

E.g. ?offset=10

phq_viewership.*

Find broadcasts by their PHQ Viewership number.

Supported suffixes are:

  • gt: greater than.

  • gte: greater than or equal to.

  • lt: less than.

  • lte: less than or equal to.

E.g. ?phq_viewership.gte=1000&phq_viewership.lte=500000

record_status

Find broadcasts by their record status. Multiple values are accepted as a comma-separated list.

Possible values:

  • active: the broadcast record is valid.

  • duplicate: the broadcast record is a duplicate of an active record.

  • deleted: the broadcast record is no longer valid.

The default is active.

E.g. ?record_status=deleted

sort

Fields to order the results by. Multiple values are accepted as a comma-separated list.

The default is start, which means the broadcasts with the earliest start dates are listed first.

Possible values:*

  • start: dates.start ascending.

  • -start: dates.start descending.

  • phq_viewership: phq_viewership ascending.

  • -phq_viewership: phq_viewership descending.

  • updated: updated ascending.

  • -updated: updated descending.

  • first_seen: first_seen ascending.

  • -first_seen: first_seen descending.

E.g. ?sort=start,-updated

start.*

Find broadcasts by their start time.

Supported suffixes are:

  • gt: greater than.

  • gte: greater than or equal to.

  • lt: less than.

  • lte: less than or equal to.

The format of start times for this parameter is YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

E.g. ?start.gte=2020-11-01T05:30:00&start.tz=America/Los_Angeles

updated

Find broadcasts by the time they were last updated. Supported suffixes are:

  • gt: greater than.

  • gte: greater than or equal to.

  • lt: less than.

  • lte: less than or equal to.

E.g. ?updated.gte=2020-11-30

Mapping File

Below is a CSV of broadcast counties. It contains the place_id and name of all counties and states in the US.

Response

Response Fields

Below are the fields returned by the Broadcasts endpoint.

Field
Description

broadcast_id string

The unique identifier.

E.g. u5aCvebffuNFpGSGNQFiU4

broadcast_status string

The schedule status of the broadcast.

Possible values:

  • scheduled: the broadcast is scheduled to be televised.

  • predicted: the broadcast is predicted to be televised.

  • cancelled: the broadcast is no longer scheduled to be televised.

E.g. scheduled

dates object

The dates field contains details about the time of the broadcast. Fields in the dates object are described below.

dates.start string

The time the broadcast is scheduled to start, in UTC. In YYYY-MM-DDThh:mm:ssZ format.

E.g. 2018-01-01T17:00:00Z

dates.start_local string

The time the broadcast is scheduled to start in the time zone of the broadcast’s location. In YYYY-MM-DDThh:mm:ss format.

E.g. 2018-01-01T12:00:00

dates.timezone string

E.g. America/New_York

duplicate_of_id string

The active record unique identifier the current broadcast is a duplicate of. Please note that this field is only present for records with record status duplicate.

E.g. u5aCvebffuNFpGSGNQFiU4

event object

The event field contains details about the physical event that is being televised in the broadcast. Fields in the event object are described below.

event.aviation_rank number

E.g. 100

event.category string

The category of the physical event.

E.g. sports

event.dates object

Details about the time of the physical event.

Fields:

  • start: the start time of the physical event.

  • start_local: the start time in the physical event’s time zone.

  • end: the end time of the physical event.

  • end_local: the end time in the physical event’s time zone.

  • predicted_end_local: the time the physical event is predicted to end in the event's time zone.

  • timezone: the time zone of the physical event.

E.g.

event.entities array

Venue entities linked to the physical event.

E.g.

event.event_id string

The unique identifier of the physical event. Events in the Broadcasts API have the same identifiers as those in the Events API.

E.g. svbfg9xT4YSVUeeAKp

event.labels array

The labels associated with the physical event.

E.g. ["american-football", "nfl", "sport"]

event.local_rank number

The Local Rank number of the physical event. Local Rank represents the physical event’s impact on its local geographical location.

E.g. 100

event.location object

Details about the location of the physical event.

Fields:

  • country: the country code.

  • geopoint: the latitude and longitude coordinates.

  • place_hierarchies: place hierarchies of the physical event.

E.g.

event.phq_attendance number

The number of people predicted to attend the physical event.

E.g. 65000

event.phq_rank number

The PHQ Rank number of the physical event. PHQ Rank represents the physical event’s impact independent of its geographical location.

E.g. 100

event.title string

The title of the physical event.

E.g. Super Bowl - 49ers vs Kansas City Chiefs

first_seen string

The time the broadcast was seen for the first time. In YYYY-MM-DDThh:mm:ssZ format.

E.g. 2020-11-30T06:58:28Z

location object

The location field contains details about where the broadcast is televised. Fields in the location object are described below.

location.country string

E.g. US

location.geopoint object

The latitude and longitude coordinates of the location where the broadcast is televised.

E.g.

location.place_hierarchies array

An array of place hierarchies for the location where the broadcast is televised. A broadcast record is only televised in one location.

E.g.

location.places array

An array of place details for the place where the broadcast is televised. A broadcast record is only televised in one place. A place object has these fields:

  • place_id: id of the place.

  • type: the type of the place. Broadcasts are located at counties or county-equivalents.

  • name: the name of the place.

  • county: the name of the Place’s county. This is the same as the name if the Place is a county.

  • region: the name of the Place’s region. In the US, regions represent states or federal districts.

E.g.

phq_viewership number

The estimated number of people in the broadcast’s location that will watch the broadcast.

E.g. 300000

record_status string

The record status of the broadcast.

Possible values:

  • active: the broadcast record is valid.

  • duplicate: the broadcast record is a duplicate of an active record.

  • deleted: the broadcast record is no longer valid.

E.g. active

updated string

The time the broadcast was last updated. In YYYY-MM-DDThh:mm:ssZ format.

E.g. 2020-11-30T06:58:28Z

Example response

Below is an example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "overflow": false,
    "results": [
        {
            "broadcast_id": "u5aCvebffuNFpGSGNQFiU4",
            "updated": "2020-11-30T06:58:28Z",
            "first_seen": "2020-11-26T01:18:24Z",
            "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
            }
        }
    ]
}

Examples

curl -X GET "https://api.predicthq.com/v1/broadcasts/?broadcast_id=u5aCvebffuNFpGSGNQFiU4" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/broadcasts/",
    headers={
      "Accept": "application/json",
      "Authorization": "Bearer $ACCESS_TOKEN"
    },
    params={
        "broadcast_id": "u5aCvebffuNFpGSGNQFiU4"
    }
)

print(response.json())

Guides

Below are some guides relevant to this API:

Find broadcasts by their physical event’s unique identifier. Multiple values are accepted as a comma-separated list. Events in the Broadcasts API have the same identifiers as those in the

Find broadcasts by their entity's unique identifier. Multiple values are accepted as a comma-separated list. Entities in the Broadcasts API have the same identifiers as those in the .

tz: time zone of the first_seen times uses a name. Default is UTC.

Places in the Broadcasts API have the same identifiers as those in the .

All broadcast location places are counties, but this parameter accepts other types of places in the hierarchy. See for different place types.

A is available. It contains the place_id and name of all counties and states in the US.

tz: time zone of the updated times used; a name. Default is UTC.

tz: time zone of the updated times used; a name. Default is UTC.

Our guide on in the API explains when the scheduled and predicted statuses are used.

The time zone of the broadcast’s location. In name format.

The number of the physical event. Aviation Rank represents the physical event’s impact on flight bookings by considering both domestic and international travel.

The country code of the location where the broadcast is televised. In format.

A hierarchy is an array of place ids (see ). The final id in a hierarchy is the place_id of the place where the broadcast is televised.

country: the country code of the Place’s country.

A is available. It contains the place_id and name of all counties and states in the US.

{
  "start": "2018-01-01T17:00:00Z",
  "end": "2018-01-01T20:43:26Z",
  "start_local": "2018-01-01T12:00:00",
  "end_local": "2018-01-01T15:43:26",
  "predicted_end_local": "2018-01-01T15:20:00",
  "timezone": "America/New_York"
}
[
  {
    "entity_id": "wVgG7p8ZKRKEPPrNDq4my9",
    "type": "venue",
    "name": "Hard Rock Stadium",
    "formatted_address": "347 Don Shula Dr\nMiami Gardens, FL 33056\nUnited States of America"
  }
]
{
  "geopoint": {
    "lon": -80.23886040000002,
    "lat": 25.9579665
  },
  "place_hierarchies": [
    [
      "6295630",
      "6255149",
      "6252001",
      "4155751",
      "4164238",
      "4161298"
    ]
  ],
  "country": "US"
}
{
  "lon": -122.4425,
  "lat": 37.77823
}
[
  [
    "6295630",
    "6255149",
    "6252001",
    "5332921",
    "5391997"
  ]
]
[
  {
    "place_id": "5391997",
    "type": "county",
    "name": "San Francisco County",
    "county": "City and County of San Francisco",
    "region": "California",
    "country": "US"
  }
]
WebApp
Live TV Event Guides
Events API
Events API
TZ Database
Places API
Places
TZ Database
TZ Database
different sport types
TZ Database
Aviation Rank
ISO 3166-1 alpha-2
Places
ISO 3166-1 alpha-2
CSV file of broadcast counties
CSV file of broadcast counties
170KB
broadcast-events-place-mapping.csv