Search GDELT TV News
gdelt_search_tvRead-only
Search US television news closed captions (2009–October 2024, 150+ stations) for spoken mentions of a query. Returns a bounded, paged per-station time series showing airtime devoted to the topic. Use the stations parameter to select networks (e.g. ["CNN", "FOXNEWS", "MSNBC"]) — the TV API requires at least one station, supplied either there or as a station: selector inside query. TV query also supports in-query operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper 360", context:"vaccine". Important: most station monitoring ended October 2024 — use gdelt_list_tv_stations to verify active date ranges before querying recent events.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum timeline points returned in this response (1–500). | |
| query | Yes | Search query for TV transcript content. Supports TV operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine". Boolean OR and phrase operators also work. | |
| offset | No | Zero-based point offset into the deterministic date-then-station ordering. Use nextOffset from the preceding response with the same query inputs to retrieve the next page. | |
| dateres | No | Optional GDELT aggregation resolution. Omit to let GDELT choose from the query window; the effective recognized or inferred resolution is returned as dateResolution. | |
| stations | No | Up to 10 station IDs to filter to (e.g. ["CNN", "FOXNEWS", "MSNBC"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid station IDs. | |
| timespan | No | Time window, e.g. "1m", "6m", "1y". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024. | |
| normalize | No | When true (default), values are normalized as % of total airtime, enabling cross-station comparison. When false, returns raw matching 15-second clip counts. | |
| smoothing | No | Smoothing window in timesteps (0 = none). Reduces noise for sporadic topics. | |
| endDatetime | No | End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected. | |
| startDatetime | No | Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| limit | No | Maximum points requested for this page. | |
| notice | No | Guidance when the query matched no TV coverage — the resolved timespan window, the October 2024 archive cutoff, and how to check station coverage. Absent when coverage was returned. | |
| offset | No | Zero-based offset of this point page. | |
| series | No | Station series represented in this point page. | |
| timeRange | No | Date range spanned by this returned point page. Omitted when the page is empty. | |
| nextOffset | No | Offset for the next page using the same query inputs. Absent when this is the final page. | |
| normalized | No | True when values are normalized coverage percentages. | |
| totalCount | No | Number of station series returned. | |
| totalPoints | No | Total points available across all matched station series before pagination. | |
| dateResolution | No | Temporal resolution of data points — as GDELT reported it, as requested via dateres, or inferred from the returned intervals. Omitted when none of those can establish it. | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. |