# Search Broadcasts

{% hint style="info" %}
**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](https://control.predicthq.com/settings/plans).
{% endhint %}

## Search Broadcasts

> Returns a paginated list of broadcast records matching the given filters. Broadcasts represent scheduled or predicted Live TV events at the county level in the US.\
> \
> Use date range filters (\`start.\*\`, \`updated.\*\`, \`first\_seen.\*\`) to narrow results by time, \`location.place\_id\` or \`location.origin\` to filter by geography, and \`event.\*\` filters to find broadcasts linked to specific physical events.\
> \
> Results are sorted by \`start\` ascending by default. Use the \`sort\` parameter to change ordering. Pagination is offset-based.

````json
{"openapi":"3.1.0","info":{"title":"PredictHQ Broadcasts API","version":"1.0.0"},"tags":[{"name":"Broadcasts API"}],"servers":[{"url":"https://api.predicthq.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"$API_KEY","description":"Enter your PredictHQ API key. The Bearer prefix is added automatically.\n\nWhen calling the API directly, send: `Authorization: Bearer <YOUR_API_KEY>` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"parameters":{"OffsetParam":{"name":"offset","in":"query","description":"The number of results to skip. Default is `0`. Use with `limit` for pagination.","required":false,"schema":{"type":"integer","default":0}},"LimitParam":{"name":"limit","in":"query","description":"The number of results to return per page. Default is `10`. Maximum is `500`.","required":false,"schema":{"type":"integer","default":10}}},"schemas":{"BroadcastsResponse":{"type":"object","properties":{"count":{"description":"The total number of results matching the query.","type":"integer","title":"Count"},"next":{"description":"URL to the next page of results, or null if this is the last page.","anyOf":[{"type":"string"},{"type":"null"}]},"previous":{"description":"URL to the previous page of results, or null if this is the first page.","anyOf":[{"type":"string"},{"type":"null"}]},"overflow":{"description":"Indicates whether the total count exceeds the maximum result window.","type":"boolean","title":"Overflow"},"results":{"description":"Array of broadcast records matching the query.","type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/PublicBroadcast"},{"$ref":"#/components/schemas/PublicDeletedBroadcast"},{"$ref":"#/components/schemas/PublicDuplicateBroadcast"}]},"title":"Results"}},"required":["count","overflow","results"],"title":"BroadcastsResponse"},"PublicBroadcast":{"type":"object","properties":{"broadcast_id":{"description":"The unique identifier.\n\n\nE.g. `u5aCvebffuNFpGSGNQFiU4`","type":"string","title":"Broadcast Id"},"updated":{"description":"The time the broadcast was last updated. In YYYY-MM-DDThh:mm:ssZ format.\n\n\nE.g. `2020-11-30T06:58:28Z`","type":"string","format":"date-time","title":"Updated"},"first_seen":{"description":"The time the broadcast was seen for the first time. In YYYY-MM-DDThh:mm:ssZ format.\n\n\nE.g. `2020-11-30T06:58:28Z`","type":"string","format":"date-time","title":"First Seen"},"dates":{"description":"The scheduled start time and time zone of the broadcast.","$ref":"#/components/schemas/PublicBroadcastDate"},"location":{"description":"The geographic location where the broadcast is televised, at the county level.","$ref":"#/components/schemas/PublicBroadcastLocation"},"phq_viewership":{"description":"The estimated number of people in the broadcast's location that will watch the broadcast.\n\n\nE.g. `300000`","type":"integer","title":"Phq Viewership"},"record_status":{"description":"The record status of the broadcast.\n\n\nPossible values:\n- active: the broadcast record is valid.\n- duplicate: the broadcast record is a duplicate of an active record.\n- deleted: the broadcast record is no longer valid.\n\n\nE.g. `active`","$ref":"#/components/schemas/ActiveBroadcastRecordStatus"},"broadcast_status":{"description":"The schedule status of the broadcast.\n\n\nOur guide on [different sport](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/find-broadcasts-for-specific-sport-types) types in the API explains when the `scheduled` and `predicted` statuses are used.\n\n\nE.g. 'scheduled'","$ref":"#/components/schemas/BroadcastStatus"},"event":{"description":"The physical event that the broadcast is linked to.","$ref":"#/components/schemas/PublicEvent"}},"required":["broadcast_id","updated","first_seen","record_status"],"title":"PublicBroadcast"},"PublicBroadcastDate":{"type":"object","properties":{"start":{"description":"The time the broadcast is scheduled to start, in UTC. In YYYY-MM-DDThh:mm:ssZ format.\n\n\nE.g. `2018-01-01T17:00:00Z`","type":"string","format":"date-time","title":"Start"},"start_local":{"description":"The time the broadcast is scheduled to start in the time zone of the broadcast's location. In YYYY-MM-DDThh:mm:ss format.\n\n\nE.g. `2018-01-01T12:00:00`","type":"string","format":"date-time","title":"Start Local"},"timezone":{"description":"The time zone of the broadcast's location. In TZ Database name format.\n\n\nE.g. `America/New_York`","type":"string","title":"Timezone"}},"required":["start"],"title":"PublicBroadcastDate"},"PublicBroadcastLocation":{"type":"object","properties":{"geopoint":{"description":"The latitude and longitude coordinates of the location where the broadcast is televised.\n\n\n**E.g.**\n  ```json\n  {\n    \"lon\": -122.4425,\n    \"lat\": 37.77823\n  }\n  ```","$ref":"#/components/schemas/GeoPoint"},"place_hierarchies":{"description":"An array of place hierarchies for the location where the broadcast is televised. A broadcast record is only televised in one location.\n\n\nA hierarchy is an array of place ids (see [Places](https://docs.predicthq.com/api/places/search-places)). The final id in a hierarchy is the place_id of the place where the broadcast is televised.\n\n**E.g.**\n  ```json\n  [\n    [\n      \"6295630\",\n      \"6255149\",\n      \"6252001\",\n      \"5332921\",\n      \"5391997\"\n    ]\n  ]\n  ```","type":"array","items":{"items":{"type":"string"},"type":"array"},"title":"Place Hierarchies"},"places":{"description":"An array of place details for the place where the broadcast is televised. A broadcast record is only televised in one place.\n\nA [CSV file of broadcast counties](https://docs.predicthq.com/api/broadcasts/search-broadcasts#mapping-file) is available. It contains the place_id and name of all counties and states in the US.\n**E.g.**\n  ```json\n  [\n    {\n      \"place_id\": \"5391997\",\n      \"type\": \"county\",\n      \"name\": \"San Francisco County\",\n      \"county\": \"City and County of San Francisco\",\n      \"region\": \"California\",\n      \"country\": \"US\"\n    }\n  ]\n  ```","type":"array","items":{"$ref":"#/components/schemas/PublicPlace"},"title":"Places"},"country":{"description":"The country code of the location where the broadcast is televised. In [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.\n\n\nE.g. `US`","type":"string","title":"Country"}},"required":["geopoint","place_hierarchies","places","country"],"title":"PublicBroadcastLocation"},"GeoPoint":{"type":"object","properties":{"lon":{"description":"Must be between -180.0 and 180.0","type":"number","exclusiveMaximum":180,"exclusiveMinimum":-180,"title":"Lon"},"lat":{"description":"Must be between -90.0 and 90.0","type":"number","exclusiveMaximum":90,"exclusiveMinimum":-90,"title":"Lat"}},"required":["lon","lat"],"title":"GeoPoint"},"PublicPlace":{"type":"object","properties":{"place_id":{"description":"id of the place","type":"string","title":"Place Id"},"type":{"description":"The type of the place. Broadcasts are located at counties or county-equivalents.","$ref":"#/components/schemas/PlaceType"},"name":{"description":"The name of the place.","type":"string","title":"Name"},"county":{"description":"The name of the Place's county. This is the same as the name if the Place is a county.","type":"string","title":"County"},"region":{"description":"The name of the Place's region. In the US, regions represent states or federal districts.","type":"string","title":"Region"},"country":{"description":"The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the Place’s country.","type":"string","title":"Country"}},"required":["place_id","type","name","county","region","country"],"title":"PublicPlace"},"PlaceType":{"type":"string","enum":["admin:city:major","locality","county"],"title":"PlaceType"},"ActiveBroadcastRecordStatus":{"type":"string","const":"active","title":"ActiveBroadcastRecordStatus"},"BroadcastStatus":{"type":"string","enum":["cancelled","predicted","scheduled"],"title":"BroadcastStatus"},"PublicEvent":{"type":"object","properties":{"event_id":{"description":"The unique identifier of the physical event. Events in the Broadcasts API have the same identifiers as those in the Events API.\n\n\nE.g. `svbfg9xT4YSVUeeAKp`","type":"string","title":"Event Id"},"title":{"description":"The title of the physical event.\n\n\nE.g. `Super Bowl - 49ers vs Kansas City Chiefs`","type":"string","title":"Title"},"category":{"description":"The category of the physical event.\n\n\nE.g. `sports`","$ref":"#/components/schemas/BroadcastEventCategory"},"labels":{"description":"The labels associated with the physical event.\n\n\nE.g. `[\"american-football\", \"nfl\", \"sport\"]`","type":"array","items":{"type":"string"},"title":"Labels"},"dates":{"description":"Details about the time of the physical event.\n\n\n**E.g.**\n  ```json\n  {\n    \"start\": \"2018-01-01T17:00:00Z\",\n    \"end\": \"2018-01-01T20:43:26Z\",\n    \"start_local\": \"2018-01-01T12:00:00\",\n    \"end_local\": \"2018-01-01T15:43:26\",\n    \"predicted_end_local\": \"2018-01-01T15:20:00\",\n    \"timezone\": \"America/New_York\"\n  }\n  ```","$ref":"#/components/schemas/PublicEventDates"},"location":{"description":"Details about the location of the physical event.\n\n\n **E.g.**\n    ```json\n    {\n      \"geopoint\": {\n        \"lon\": -80.23886040000002,\n        \"lat\": 25.9579665\n      },\n      \"place_hierarchies\": [\n        [\n          \"6295630\",\n          \"6255149\",\n          \"6252001\",\n          \"4155751\",\n          \"4164238\",\n          \"4161298\"\n        ]\n      ],\n      \"country\": \"US\"\n    }\n    ```","$ref":"#/components/schemas/PublicEventLocation"},"entities":{"description":"Venue entities linked to the physical event.\n\n\n**E.g.**\n  ```json\n  [\n    {\n      \"entity_id\": \"wVgG7p8ZKRKEPPrNDq4my9\",\n      \"type\": \"venue\",\n      \"name\": \"Hard Rock Stadium\",\n      \"formatted_address\": \"347 Don Shula Dr\\nMiami Gardens, FL 33056\\nUnited States of America\"\n    }\n  ]\n  ```","type":"array","items":{"$ref":"#/components/schemas/PublicEntity"},"title":"Entities"},"phq_attendance":{"description":"The number of people predicted to attend the physical event.\n\n\nE.g. `65000`","type":"integer","title":"Phq Attendance"},"phq_rank":{"description":"The PHQ Rank number of the physical event. PHQ Rank represents the physical event's impact independent of its geographical location.\n\n\nE.g. `100`","type":"integer","title":"Phq Rank"},"local_rank":{"description":"The Local Rank number of the physical event. Local Rank represents the physical event's impact on its local geographical location.\n\n\nE.g. `100`","type":"integer","title":"Local Rank"},"aviation_rank":{"description":"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.\n\n\nE.g. `100`","type":"integer","deprecated":true,"title":"Aviation Rank"}},"required":["event_id","title","category","labels","dates","location","entities"],"title":"PublicEvent"},"BroadcastEventCategory":{"type":"string","const":"sports","title":"BroadcastEventCategory"},"PublicEventDates":{"type":"object","properties":{"start":{"description":"The start time of the physical event.","type":"string","format":"date-time","title":"Start"},"end":{"description":"The end time of the physical event.","type":"string","format":"date-time","title":"End"},"start_local":{"description":"The start time in the physical event's time zone.","type":"string","format":"date-time","title":"Start Local"},"end_local":{"description":"The end time in the physical event's time zone.","type":"string","format":"date-time","title":"End Local"},"predicted_end_local":{"description":"the time the physical event is predicted to end in the event's time zone","type":"string","format":"date-time","title":"Predicted End Local"},"timezone":{"description":"The time zone of the physical event.","type":"string","title":"Timezone"}},"required":["start","start_local","timezone"],"title":"PublicEventDates"},"PublicEventLocation":{"type":"object","properties":{"geopoint":{"description":"The latitude and longitude coordinates.","$ref":"#/components/schemas/GeoPoint"},"place_hierarchies":{"description":"Place hierarchies of the physical event.","type":"array","items":{"items":{"type":"string"},"type":"array"},"title":"Place Hierarchies"},"country":{"description":"The country code.","type":"string","title":"Country"}},"required":["geopoint","place_hierarchies","country"],"title":"PublicEventLocation"},"PublicEntity":{"type":"object","properties":{"entity_id":{"description":"The unique identifier of the entity.","type":"string","title":"Entity Id"},"type":{"description":"The type of entity. Either `venue` or `organisation`.","$ref":"#/components/schemas/BroadcastEntityType"},"name":{"description":"The name of the entity.","type":"string","title":"Name"},"formatted_address":{"description":"The formatted address of the entity, if available.","type":"string","title":"Formatted Address"}},"required":["entity_id","type","name"],"title":"PublicEntity"},"BroadcastEntityType":{"type":"string","enum":["venue","organisation"],"title":"BroadcastEntityType"},"PublicDeletedBroadcast":{"type":"object","properties":{"broadcast_id":{"description":"The unique identifier.\n\n\nE.g. `u5aCvebffuNFpGSGNQFiU4`","type":"string","title":"Broadcast Id"},"updated":{"description":"The time the broadcast was last updated. In YYYY-MM-DDThh:mm:ssZ format.\n\n\nE.g. `2020-11-30T06:58:28Z`","type":"string","format":"date-time","title":"Updated"},"first_seen":{"description":"The time the broadcast was seen for the first time. In YYYY-MM-DDThh:mm:ssZ format.\n\n\nE.g. `2020-11-30T06:58:28Z`","type":"string","format":"date-time","title":"First Seen"},"record_status":{"description":"The record status of the broadcast. Always `deleted` for this record type.","$ref":"#/components/schemas/DeletedBroadcastRecordStatus"}},"required":["broadcast_id","updated","first_seen","record_status"],"title":"PublicDeletedBroadcast"},"DeletedBroadcastRecordStatus":{"type":"string","const":"deleted","title":"DeletedBroadcastRecordStatus"},"PublicDuplicateBroadcast":{"type":"object","properties":{"broadcast_id":{"description":"The unique identifier.\n\n\nE.g. `u5aCvebffuNFpGSGNQFiU4`","type":"string","title":"Broadcast Id"},"updated":{"description":"The time the broadcast was last updated. In YYYY-MM-DDThh:mm:ssZ format.","type":"string","format":"date-time","title":"Updated"},"first_seen":{"description":"The time the broadcast was seen for the first time. In YYYY-MM-DDThh:mm:ssZ format.\n\n\nE.g. `2020-11-30T06:58:28Z`","type":"string","format":"date-time","title":"First Seen"},"record_status":{"description":"The record status of the broadcast. Always `duplicate` for this record type.","$ref":"#/components/schemas/DuplicateBroadcastRecordStatus"},"duplicate_of_id":{"description":"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`.\n\n\nE.g. `u5aCvebffuNFpGSGNQFiU4`","type":"string","title":"Duplicate Of Id"}},"required":["broadcast_id","updated","first_seen","record_status","duplicate_of_id"],"title":"PublicDuplicateBroadcast"},"DuplicateBroadcastRecordStatus":{"type":"string","const":"duplicate","title":"DuplicateBroadcastRecordStatus"},"ErrorResponse":{"type":"object","properties":{"error":{"description":"Error message","type":"string","title":"Error"}},"required":["error"],"title":"ErrorResponse"},"HTTPValidationError":{"type":"object","properties":{"error":{"description":"Error summary message","type":"string","title":"Error"},"details":{"description":"List of validation error details","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Details"}},"required":["error","details"],"title":"HTTPValidationError"},"ValidationErrorDetail":{"type":"object","properties":{"field":{"description":"The field that failed validation","type":"string","title":"Field"},"msg":{"description":"The validation error message","type":"string","title":"Message"},"type":{"description":"The type of validation error","type":"string","title":"Error Type"}},"required":["field","msg","type"],"title":"ValidationErrorDetail"},"QueryValidationError":{"type":"object","properties":{"error":{"description":"List of query parameter validation errors","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Error"}},"required":["error"],"title":"QueryValidationError"}}},"paths":{"/v1/broadcasts/":{"get":{"operationId":"list_broadcasts","summary":"Search Broadcasts","description":"Returns a paginated list of broadcast records matching the given filters. Broadcasts represent scheduled or predicted Live TV events at the county level in the US.\n\nUse date range filters (`start.*`, `updated.*`, `first_seen.*`) to narrow results by time, `location.place_id` or `location.origin` to filter by geography, and `event.*` filters to find broadcasts linked to specific physical events.\n\nResults are sorted by `start` ascending by default. Use the `sort` parameter to change ordering. Pagination is offset-based.","parameters":[{"name":"broadcast_id","in":"query","description":"Find broadcasts by unique identifier. \n\nMultiple values are accepted as a comma-separated list.","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Broadcast Id"}},{"name":"record_status","in":"query","description":"Find broadcasts by their record status. Multiple values are accepted as a comma-separated list. Defaults to `active`.\n\n\nPossible values:\n- `active`: the broadcast record is valid.\n- `deleted`: the broadcast record is no longer valid.\n- `duplicate`: the broadcast record is a duplicate of an active record.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["active","deleted","duplicate"]},"default":["active"],"title":"Record Status"}},{"name":"broadcast_status","in":"query","description":"The schedule status of the broadcast.\n\n\nPossible values:\n- `scheduled`: the broadcast is scheduled to be televised.\n- `predicted`: the broadcast is predicted to be televised.\n- `cancelled`: the broadcast is no longer scheduled to be televised.\n\n\nOur guide on [different sport types](https://docs.predicthq.com/getting-started/guides/live-tv-event-guides/find-broadcasts-for-specific-sport-types) in the API explains when the scheduled and predicted statuses are used.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["cancelled","predicted","scheduled"]},"title":"Broadcast Status"}},{"name":"start.gt","in":"query","description":"Find broadcasts by their start time: greater than.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Start.Gt"}},{"name":"start.gte","in":"query","description":"Find broadcasts by their start time: greater than or equal to.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Start.Gte"}},{"name":"start.lt","in":"query","description":"Find broadcasts by their start time: less than.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Start.Lt"}},{"name":"start.lte","in":"query","description":"Find broadcasts by their start time: less than or equal to.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Start.Lte"}},{"name":"start.tz","in":"query","description":"Time zone of the updated times used; \n\na [TZ Database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\n\nDefault is UTC","required":false,"schema":{"type":"string","title":"Start.Tz"}},{"name":"updated.gt","in":"query","description":"Find broadcasts by the time they were last updated: greater than.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Updated.Gt"}},{"name":"updated.gte","in":"query","description":"Find broadcasts by the time they were last updated: greater than or equal to.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Updated.Gte"}},{"name":"updated.lt","in":"query","description":"Find broadcasts by the time they were last updated: less than.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Updated.Lt"}},{"name":"updated.lte","in":"query","description":"Find broadcasts by the time they were last updated: less than or equal to.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"Updated.Lte"}},{"name":"updated.tz","in":"query","description":"Time zone of the updated times used; \n\na [TZ Database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\n\nDefault is UTC","required":false,"schema":{"type":"string","title":"Updated.Tz"}},{"name":"first_seen.gt","in":"query","description":"Find broadcasts by the time they were seen for the first time: greater than.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"First Seen.Gt"}},{"name":"first_seen.gte","in":"query","description":"Find broadcasts by the time they were seen for the first time: greater than or equal to.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"First Seen.Gte"}},{"name":"first_seen.lt","in":"query","description":"Find broadcasts by the time they were seen for the first time: less than.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"First Seen.Lt"}},{"name":"first_seen.lte","in":"query","description":"Find broadcasts by the time they were seen for the first time: less than or equal to.\n\nFormat: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss","required":false,"schema":{"type":"string","title":"First Seen.Lte"}},{"name":"first_seen.tz","in":"query","description":"Time zone of the first_seen times used; \n\na [TZ Database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\n\nDefault is UTC","required":false,"schema":{"type":"string","title":"First Seen.Tz"}},{"name":"phq_viewership.gt","in":"query","description":"Find broadcasts by their PHQ Viewership number: greater than the specified value.","required":false,"schema":{"type":"integer","title":"Phq Viewership.Gt"}},{"name":"phq_viewership.gte","in":"query","description":"Find broadcasts by their PHQ Viewership number: greater than or equal to the specified value.","required":false,"schema":{"type":"integer","title":"Phq Viewership.Gte"}},{"name":"phq_viewership.lt","in":"query","description":"Find broadcasts by their PHQ Viewership number: less than the specified value.","required":false,"schema":{"type":"integer","title":"Phq Viewership.Lt"}},{"name":"phq_viewership.lte","in":"query","description":"Find broadcasts by their PHQ Viewership number: less than or equal to the specified value.","required":false,"schema":{"type":"integer","title":"Phq Viewership.Lte"}},{"name":"location.place_id","in":"query","description":"Find broadcasts by their location's place_id. Multiple values are accepted as a comma-separated list.\n\n\nPlaces in the Broadcasts API have the same identifiers as those in the [Places API](https://docs.predicthq.com/api/places/search-places).\n\n\nAll broadcast location places are counties, but this parameter accepts other types of places in the hierarchy. See [Places](https://docs.predicthq.com/api/places/search-places) for different place types.\n\nIf the `place_id` of a county is specified, broadcasts in that county will be returned.\n\nIf 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.\n\nFor 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`.\n\nA [CSV](https://docs.predicthq.com/api/broadcasts/search-broadcasts#mapping-file) file of broadcast counties is available. It contains the place_id and name of all counties and states in the US.","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Location.Place Id"}},{"name":"location.origin","in":"query","description":"Find broadcasts in the county for the provided geopoint (a latitude and longitude coordinate). The format of the geopoint is `{latitude},{longitude}`.\n\n\nThe 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.\n\n\nIf you specify a geopoint within Los Angeles County then broadcasts for Los Angeles County will be returned.","required":false,"schema":{"type":"string","title":"Location.Origin"}},{"name":"sort","in":"query","description":"Field to sort results by. Prefix with `-` for descending order. Accepts: `start`, `-start`, `phq_viewership`, `-phq_viewership`, `updated`, `-updated`, `first_seen`, `-first_seen`. Defaults to `start` (earliest first).","required":false,"schema":{"type":"array","items":{"type":"string","enum":["start","-start","phq_viewership","-phq_viewership","updated","-updated","first_seen","-first_seen"]},"default":["start"],"title":"Sort"}},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"event.event_id","in":"query","description":"Find broadcasts by their physical event’s unique identifier. Multiple values are accepted as a comma-separated list.\nEvents in the Broadcasts API have the same identifiers as those in the [Events API](https://docs.predicthq.com/api/events/search-events).","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Event.Event Id"}},{"name":"event.category","in":"query","description":"Find broadcasts by their physical event’s category.","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Event.Category"}},{"name":"event.label","in":"query","description":"Find broadcasts by their physical event’s labels. Multiple values are accepted as a comma-separated list.\n\nWhere multiple labels are provided, broadcasts which match any of the labels are returned.\n\nPlease note that all event labels are lowercase and that the search is case sensitive.","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Event.Label"}},{"name":"event.entity_id","in":"query","description":"Find broadcasts by their entity's unique identifier. Multiple values are accepted as a comma-separated list.\nEntities in the Broadcasts API have the same identifiers as those in the [Events API](https://docs.predicthq.com/api/events/search-events).\n\nThis 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.","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Event.Entity Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/HTTPValidationError"},{"$ref":"#/components/schemas/QueryValidationError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Broadcasts API"]}}}}
````

## Examples

{% tabs %}
{% tab title="curl" %}

```bash
curl -X GET "https://api.predicthq.com/v1/broadcasts/?broadcast_id=u5aCvebffuNFpGSGNQFiU4" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
```

{% endtab %}

{% tab title="python" %}

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

{% endtab %}
{% endtabs %}

## OpenAPI Spec

The OpenAPI spec for Broadcasts API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Broadcasts+API).

## Guides

{% hint style="info" %}
**USA Counties Mapping File**\
Counties are mapped to Place IDs. The current mapping of counties to Place ID can be [found here](https://github.com/predicthq/api-specs/blob/main/data/broadcast-county-place-mapping.csv).
{% endhint %}

Below are some guides relevant to this&#x20;

Below are some guides relevant to this API:

* [Live TV Event Guides](/getting-started/guides/live-tv-event-guides.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.predicthq.com/api/broadcasts/search-broadcasts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.