Broadcasts
The Broadcasts API gives you a read-only interface to PredictHQ’s Live TV Events data. The API returns broadcasts; a broadcast represents a physical event broadcasted on a television network, at a specific date, time, and location.
Search Broadcasts
Use the parameters described below to search and filter all broadcasts that are available to your account.
Visibility Window
Please note that you will not receive an error when requesting a date range and/or location that is outside of your subscription's broadcast visibility window. Instead, your visibility window will be automatically applied to your results.
Your plan’s visibility window is shown in your plan summary.
Result Limit
Please note the number of results returned will be limited to your subscription's result limit. If more results exist, the overflow field will be set to true to indicate the count number has been capped to your pagination limit.
Your plan’s pagination limits are shown in your plan summary.
Parameters
Parameter |
Description |
---|---|
broadcast_id |
Find broadcasts by unique identifier. Multiple values are accepted as a comma-separated list. E.g. |
broadcast_status |
Find broadcasts by broadcast status. Multiple values are accepted as a comma-separated list. Possible values:
E.g. |
event.category |
Find broadcasts by their physical event’s category. Possible values:
E.g. |
event.event_id |
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 Events API. E.g. |
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. |
limit |
The maximum number of results to return per page. The default limit is E.g. |
location.place_id |
Find broadcasts by their location's Places in the Broadcasts API have the same identifiers as those in the Places API. All broadcast location places are counties, but this parameter accepts other types of places in the hierarchy. See Places for different place types.
A CSV file of broadcast counties is available.
It contains the E.g. |
location.origin |
Find broadcasts in the county for the provided geopoint (a latitude/longitude).
The format of the geopoint is The broadcast endpoint returns broadcasts within a county.
When you specify a lat/long using If you specify a lat/long within LA County then broadcasts for LA County will be returned. E.g. |
offset |
The number of results to skip. The default is E.g. |
phq_viewership.* |
Find broadcasts by their PHQ Viewership number. Supported suffixes are:
E.g. |
record_status |
Find broadcasts by their record status. Multiple values are accepted as a comma-separated list. Possible values:
The default is E.g. |
sort |
Fields to order the results by. Multiple values are accepted as a comma-separated list. The default is Possible values:
E.g. |
start.* |
Find broadcasts by their start time. Supported suffixes are:
The format of start times for this parameter is E.g. |
updated |
Find broadcasts by the time they were last updated. Supported suffixes are:
The format of updated times for this parameter is E.g. |
Broadcast Fields
Below are the fields returned by the Broadcasts endpoint. Please note that these are not the fields used for filtering – refer to the Search Broadcasts section to discover which parameters can be used to filter broadcasts.
JSON Schemas are available for the Broadcasts endpoint and for a single broadcast:
Field |
Description |
---|---|
broadcast_id string |
The unique identifier. E.g. |
broadcast_status string |
The schedule status of the broadcast. Possible values:
E.g. |
dates object |
The |
dates.start string |
The time the broadcast is scheduled to start, in UTC. In E.g. |
dates.start_local string |
The time the broadcast is scheduled to start in the time zone of the broadcast’s location.
In E.g. |
dates.timezone string |
The time zone of the broadcast’s location. In TZ Database name format. E.g. |
event object |
The |
event.aviation_rank number |
The Aviation Rank number of the physical event. Aviation Rank represents the physical event’s impact on flight bookings by considering both domestic and international travel. E.g. |
event.category string |
The category of the physical event. E.g. |
event.dates object |
Details about the time of the physical event. Fields:
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. |
event.labels array |
The labels associated with the physical event. E.g. |
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. |
event.location object |
Details about the location of the physical event. Fields:
E.g. |
event.phq_attendance number |
The number of people predicted to attend the physical event. E.g. |
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. |
event.title string |
The title of the physical event. E.g. |
location object |
The |
location.country string |
The country code of the location where the broadcast is televised. In ISO 3166-1 alpha-2 format. E.g. |
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. A hierarchy is an array of place ids (see Places). The final id in a hierarchy is the place_id of the place where the broadcast is televised. 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:
A CSV file of broadcast counties is available. It contains the E.g. |
phq_viewership number |
The estimated number of people in the broadcast’s location that will watch the broadcast. E.g. |
record_status string |
The record status of the broadcast. Possible values:
E.g. |
updated string |
The time the broadcast was last updated. In E.g. |