Broadcasts API

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_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 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.event_id=svbfg9xT4YSVUeeAKp
event.entity_id 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 Events API.
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.
  • tz: time zone of the first_seen times used;a TZ Database name. Default is UTC.
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.
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.
  • 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.
A CSV file of broadcast counties is available. It contains the place_id and name of all counties and states in the US.
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.
  • tz: time zone of the updated times used; a TZ Database name. Default is UTC.
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.
  • tz: time zone of the updated times used; a TZ Database name. Default is UTC.
E.g. ?updated.gte=2020-11-30

Action

GET /v1/broadcasts/

Example

curl -X GET https://api.predicthq.com/v1/broadcasts/?broadcast_id=u5aCvebffuNFpGSGNQFiU4 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
{
    "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
            }
        }
    ]
}

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

Our guide on different sport types in the API explains when the scheduled and predicted statuses are used.
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
The time zone of the broadcast’s location. In TZ Database name format.
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
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. 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. {"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"}
event.entities
array
Venue entities linked to the physical event.
E.g. [{"entity_id": "wVgG7p8ZKRKEPPrNDq4my9", "type": "venue", "name": "Hard Rock Stadium", "formatted_address": "347 Don Shula Dr\nMiami Gardens, FL 33056\nUnited States of America"}]
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:
E.g. {"geopoint": {"lon": -80.23886040000002, "lat": 25.9579665}, "place_hierarchies": [["6295630", "6255149", "6252001", "4155751", "4164238", "4161298"]], "country": "US"}
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
The country code of the location where the broadcast is televised. In ISO 3166-1 alpha-2 format.
E.g. US
location.geopoint
object
The latitude and longitude coordinates of the location where the broadcast is televised.
E.g. {"lon": -122.4425, "lat": 37.77823}
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. [["6295630", "6255149", "6252001", "5332921", "5391997"]]
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.
  • country: the ISO 3166-1 alpha-2 country code of the Place’s country.

A CSV file of broadcast counties is available. It contains the place_id and name of all counties and states in the US.
E.g. [{"place_id": "5391997", "type": "county", "name": "San Francisco County", "county": "City and County of San Francisco", "region": "California", "country": "US"}]
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

Retrieve Broadcasts Count

This endpoint accepts the same parameters as the ones described in Search Broadcasts and can be used to get aggregated counts of all matching broadcasts that are available to your account.

A JSON Schema is available for the Broadcasts Count endpoint: broadcasts-count-response-schema.json

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.

Action

GET /v1/broadcasts/count/

Example

curl -X GET https://api.predicthq.com/v1/broadcasts/count/?event.event_id=AdKtL974inQB7GURRd \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
{
    "count": 3142
}