Search Broadcasts
Search for Live TV broadcasts happening in a location.
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.
GET https://api.predicthq.com/v1/broadcasts/
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:
E.g. ?broadcast_status=scheduled |
event.category | Find broadcasts by their physical event’s category.
Possible values:
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:
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.
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 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:
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:
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:*
E.g. ?sort=start,-updated |
start.* | Find broadcasts by their start time.
Supported suffixes are:
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:
E.g. ?updated.gte=2020-11-30 |
Below is a CSV of broadcast counties. It contains the
place_id
and name of all counties and states in the US.broadcast-events-place-mapping.csv
170KB
Text
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:
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 |
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:
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 |
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:
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:
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 |
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
}
}
]
}
curl
python
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())
Below are some guides relevant to this API:
Last modified 2mo ago