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.

Your subscription settings can be viewed in the WebApp.

Search Broadcasts

get

Authorizations

Query parameters

broadcast_idstring[]Optional

Find broadcasts by unique identifier.

Multiple values are accepted as a comma-separated list.

Example: ?broadcast_id=tFk2LbcpzgeuLXw8dKWa3J

start.gtstringOptional

Find broadcasts by their start time: greater than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

start.gtestringOptional

Find broadcasts by their start time: greater than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

start.ltstringOptional

Find broadcasts by their start time: less than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

start.ltestringOptional

Find broadcasts by their start time: less than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

start.tzstringOptional

Time zone of the updated times used;

a TZ Database name.

Default is UTC

updated.gtstringOptional

Find broadcasts by the time they were last updated: greater than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

updated.gtestringOptional

Find broadcasts by the time they were last updated: greater than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

updated.ltstringOptional

Find broadcasts by the time they were last updated: less than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

updated.ltestringOptional

Find broadcasts by the time they were last updated: less than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

updated.tzstringOptional

Time zone of the updated times used;

a TZ Database name.

Default is UTC

first_seen.gtstringOptional

Find broadcasts by the time they were seen for the first time: greater than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

first_seen.gtestringOptional

Find broadcasts by the time they were seen for the first time: greater than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

first_seen.ltstringOptional

Find broadcasts by the time they were seen for the first time: less than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

first_seen.ltestringOptional

Find broadcasts by the time they were seen for the first time: less than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

first_seen.tzstringOptional

Time zone of the first_seen times used;

a TZ Database name.

Default is UTC

phq_viewership.gtintegerOptional

Find broadcasts by their PHQ Viewership number: greater than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

phq_viewership.gteintegerOptional

Find broadcasts by their PHQ Viewership number: greater than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

phq_viewership.ltintegerOptional

Find broadcasts by their PHQ Viewership number: less than.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

phq_viewership.lteintegerOptional

Find broadcasts by their PHQ Viewership number: less than or equal to.

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss

location.place_idstring[]Optional

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.

Example: ?location.place_id=5391997,5128594,5379524,5129915

location.originstringOptional

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.

Example: ?location.origin=40.730610,-73.935242

offsetintegerOptional

Offset the results.

Default: 0

limitintegerOptional

Limit the number of results.

Default: 10

event.event_idstring[]Optional

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.

Example: ?event.event_id=svbfg9xT4YSVUeeAKp

event.categorystring[]Optional

Find broadcasts by their physical event’s category.

Example: ?event.category=sports

event.labelstring[]Optional

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.

Example: ?event.label=nfl,nba

event.entity_idstring[]Optional

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.

Example: ?event.entity_id=GduZL2z24phJQni4ktERGw

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

GET /v1/broadcasts/ HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "next": "text",
  "previous": "text",
  "overflow": true,
  "results": [
    {
      "broadcast_id": "text",
      "updated": "2025-10-04T15:06:57.264Z",
      "first_seen": "2025-10-04T15:06:57.264Z",
      "dates": {
        "start": "2025-10-04T15:06:57.264Z",
        "start_local": "2025-10-04T15:06:57.264Z",
        "timezone": "text"
      },
      "location": {
        "geopoint": {
          "lon": 1,
          "lat": 1
        },
        "place_hierarchies": [
          [
            "text"
          ]
        ],
        "places": [
          {
            "place_id": "text",
            "type": "admin:city:major",
            "name": "text",
            "county": "text",
            "region": "text",
            "country": "text"
          }
        ],
        "country": "text"
      },
      "phq_viewership": 1,
      "record_status": "text",
      "broadcast_status": "cancelled",
      "event": {
        "event_id": "text",
        "title": "text",
        "category": "text",
        "labels": [
          "text"
        ],
        "dates": {
          "start": "2025-10-04T15:06:57.264Z",
          "end": "2025-10-04T15:06:57.264Z",
          "start_local": "2025-10-04T15:06:57.264Z",
          "end_local": "2025-10-04T15:06:57.264Z",
          "predicted_end_local": "2025-10-04T15:06:57.264Z",
          "timezone": "text"
        },
        "location": {
          "geopoint": {
            "lon": 1,
            "lat": 1
          },
          "place_hierarchies": [
            [
              "text"
            ]
          ],
          "country": "text"
        },
        "entities": [
          {
            "entity_id": "text",
            "type": "venue",
            "name": "text",
            "formatted_address": "text"
          }
        ],
        "phq_attendance": 1,
        "phq_rank": 1,
        "local_rank": 1,
        "aviation_rank": 1
      }
    }
  ]
}

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())

OpenAPI Spec

The OpenAPI spec for Broadcasts API can be found here.

Guides

USA Counties Mapping File Counties are mapped to Place IDs. The current mapping of counties to Place ID can be found here.

Below are some guides relevant to this

Below are some guides relevant to this API:

Live TV Event Guides

PreviousGet Event Counts NextGet Broadcasts Count

Last updated 9 days ago

Was this helpful?