Live TV Events with the Broadcasts API
PredictHQ’s Live TV Events feature enables our customers to identify how many people will watch a TV broadcast at a given location.
You can also find a more detailed documentation about PredictHQ’s Live TV Events in our Category Info guides.
The initial release of Live TV Events is focused on live sports broadcasts in the United States. With this release, customers can query to see how many people within a given county will watch a live sports game. For example, for the Green Bay Packers vs San Francisco 49ers game in San Jose, you can use our API to find that 129,085 people will watch the live broadcast of that game in Alameda County in Oakland on November 24, 2019.
Using our Broadcasts API, customers can query to find the number of people watching a game in a location. We provide both historic data (from 1 Jan 2018) and predicted viewership for two weeks from the current date. Customers can use this to model how Live TV Events have impacted their business in the past to inform accurate forecasts based on our future-looking TV viewership data.
A key use case for this is within demand forecasting. For example, delivery companies may find when relevant sports games are being played so they can plan for spikes in deliveries. Using our Broadcasts API companies can integrate Live TV Events features into their forecasting models to increase forecast accuracy.
This page outlines how to get started with the Broadcasts API so customers can use it to find Live TV Events information. The Broadcasts API provides Live TV Events data by returning broadcast records. A broadcast record represents how many people will watch a physical event broadcasted on a television network, at a specific date, time and location.
Search broadcasts by county place_id and start time
Find broadcasts televised in specific county locations and time ranges
For the following example, we want to find all broadcasts televised in two counties in California during November 2020.
The location.place_id parameter allows us to filter live sports events by their broadcast locations. For the counties in our example, we will use location.place_id=5368381,5391832, which are the respective place_ids for Los Angeles County and San Diego County in California.
These ids were found using the Places API. We provide a CSV file of broadcast counties to download, to make it easier to discover the place_id for all counties and states in the US.
We can also use the start.* parameters to filter broadcasts by time. For the time range in our example, we will use start.gte=2020-11-01 and start.lte=2020-11-30. Using start.tz=America/Los_Angeles will treat the parameter’s start dates and times in the America/Los_Angeles time zone, otherwise the parameter dates and times will be treated as UTC.
curl -X GET -G "https://api.predicthq.com/v1/broadcasts/" \
-d location.place_id=5368381,5391832 \
-d start.gte=2020-11-01 \
-d start.lte=2020-11-30 \
-d start.tz=America/Los_Angeles \
-H "Authorization: Bearer $ACCESS_TOKEN"A snippet of the results are shown below:
{
"count": 501,
"results": [
{
"broadcast_id": "6v4RTik6YVhkLr9HpyddHJ",
"dates": {
"start": "2020-11-01T18:00:00Z",
"start_local": "2020-11-01T10:00:00",
"timezone": "America/Los_Angeles"
},
"location": {
"places": [
{
"place_id": "5391832",
"name": "San Diego County",
...
}
],
"country": "US"
},
"phq_viewership": 184637,
"event": {
"event_id": "24HwKWjyPw3xLBhGza",
"title": "Los Angeles Rams vs Miami Dolphins",
"labels": ["american-football", "nfl", "closed-doors", "sport"],
...In this example, the Broadcasts API found 501 broadcasts. The snippet shows one of the broadcasts: an NFL game where 184637 people will watch the broadcast.
Search broadcasts by latitude and longitude coordinates
Find broadcasts televised in the county for a geopoint
For the following example, we want to find all broadcasts televised in the county that corresponds to a geopoint (latitude and longitude coordinates).
The location.origin parameter allows us to filter broadcasts by a geopoint, such as the location of a store. The Broadcasts API returns broadcasts for the county the geopoint is located in. For our example, we have a store located in Union Square, San Francisco, which has a latitude of 37.7879 and longitude of -122.4097. So we will use location.origin=37.7879,-122.4097. Using these coordinates will return broadcasts for San Francisco County - the county which Union Square is in.
We can also use the sort parameter to order the broadcasts returned by the API. For our example, we will use sort=-start to return the most recently televised broadcasts first.
curl -X GET -G "https://api.predicthq.com/v1/broadcasts/" \
-d location.origin=37.7879,-122.4097 \
-d sort=-start \
-H "Authorization: Bearer $ACCESS_TOKEN"A snippet of the results are shown below:
{
"count": 15486,
"results": [
{
"broadcast_id": "39r9LVVFHzcRM2RvwDfHq7u",
"dates": {
"start": "2021-03-05T01:30:00Z",
"start_local": "2021-03-04T17:30:00",
"timezone": "America/Los_Angeles"
},
"location": {
"geopoint": {
"lon": -122.4425,
"lat": 37.77823
},
"places": [
{
"place_id": "5391997",
"type": "county",
"name": "San Francisco County",
"region": "California",
...
}
],
...
},
"phq_viewership": 1053,
"event": {
"event_id": "5vJDzni9R52scG466o",
"title": "Miami Heat vs New Orleans Pelicans",
...In this example, the Broadcasts API found and returned 15486 broadcasts in San Francisco County. The snippet shows the broadcast with the latest start time at the time the API was called.
Find broadcasts for specific events
Find broadcasts televised in all locations for a sports event
In this example, we want to find the broadcasts for the Super Bowl game, New England Patriots vs Los Angeles Rams, played on February 3rd 2019.
To find broadcasts for an event, we can use the event.event_id parameter. This parameter allows us to retrieve broadcast records for each county the game has viewership in. So, for a specific game televised nation-wide, the API would return over 3000 broadcast records with viewership per county.
The 2019 Super Bowl game's event_id is ePQLUqbPnMn3mQhe35, so we need to filter broadcasts using event.event_id=ePQLUqbPnMn3mQhe35. The event_id was found using our Events API. See our Events API documentation to discover how to query for other sports events.
curl -X GET "https://api.predicthq.com/v1/broadcasts/?event.event_id=ePQLUqbPnMn3mQhe35" \
-H "Authorization: Bearer $ACCESS_TOKEN"A snippet of the results are shown below:
{
"count": 3055,
"results": [
{
"broadcast_id": "V75qDgQ8wrq4Qp36nFVThm",
"dates": {
"start": "2019-02-03T23:30:00Z",
"start_local": "2019-02-03T18:30:00",
"timezone": "America/New_York"
},
"location": {
"places": [
{
"place_id": "4945455",
"name": "Norfolk County",
"region": "Massachusetts",
...
}
],
"country": "US"
},
"phq_viewership": 308374,
"event": {
"event_id": "ePQLUqbPnMn3mQhe35",
"title": "Super Bowl - New England Patriots vs Los Angeles Rams",
...3055 broadcasts were found, which means the Super Bowl game was televised in 3055 counties in the US. The snippet shows one of the results: a broadcast in Norfolk County, Massachusetts where 308374 people in Norfolk County will watch the game.
Find broadcasts for different sport types
How different sport types have scheduled and predicted broadcast_status
In this example, we explain when the different broadcast_status values are used and how to search for broadcasts for different sports.
Our Broadcasts API provides broadcast and viewership data for sports with the top viewership in the US. These include broadcasts for games played in the seven top US leagues: NFL, NBA, NHL, MLB, MLS, D1 NCAA Basketball, D1 NCAA Football, and also broadcasts for other sports events with high viewership.
Broadcasts for the seven top US leagues have a broadcast_status of scheduled. We enrich our data with television listings to determine their televised time and location (county). The scheduled broadcast_status is for these broadcasts where we know the date, time and location of a TV broadcast based on TV schedule information.
Broadcasts for sports other than the seven leagues have a broadcast_status of predicted since we predict their televised time and location (county). The predicted broadcast_status 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). These are typically one-off events or are finals of their respective competitions, such as the 2019 NCAA Women's Basketball Final.
For broadcasts with a predicted broadcast_status, 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 pretty good prediction of who will be watching these large events. Customers may want to use the broadcast_status to indicate the confidence of a broadcast airing; they may build this as a feature or to treat scheduled broadcasts differently from predicted.
The API returns broadcasts of all broadcast_status values by default. The broadcast_status parameter allows us to filter broadcasts with a particular status. The Broadcasts API also supports the event.label parameter which can be used to find broadcasts for specific sport types. In this example, we show an API query using the broadcast_status and event.label parameters which returns broadcasts for the 2019 NCAA Women’s Basketball Final amongst other matching results. You can discover available sport types and event labels by Searching Live TV Events in Control Center or using the Events API.
Aggregating Live TV Events data
Aggregating results from the Broadcasts API to create features for forecasting is an impactful way to unlock the value of Live TV Events data. You can use the features API to aggregate broadcast data. See the PHQ viewership in the endpoint documentation. Using these features you can get the count, sum, min, max, avg, median, and std_dev for any viewership feature in the features API. The features API will combine all the viewership data for a location and return these calculated values. For example, you can get the total NFL viewership and NBA viewership per day for a location as shown below
POST /v1/features HTTP/1.1
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN
{
"active": {
"gte": "2020-02-01",
"lte": "2020-02-29"
},
"location": {
"place_id": [
5224323,
5811704,
4887398
]
},
"phq_viewership_sports_american_football_nfl": {
"stats": [
"count",
"sum",
"avg"
]
},
"phq_viewership_sports_basketball_nba": {
"stats": [
"count",
"sum",
"avg"
]
}
}