Search GDELT TV News
gdelt_search_tvRead-only
Search television news closed captions for spoken mentions of a query. Returns a bounded, paged per-station time series showing airtime devoted to the topic — 500 points by default, up to 20,000 per page. Each series carries GDELT's display name for the station and, when that name resolves to one, the station ID gdelt_get_tv_clips takes as stations. Use stations to select station IDs (e.g. ["CNN", "FOXNEWS", "MSNBC"]), or select with station:, network:, or quoted market: operators in query. TV query also supports in-query operators: station:CNN, network:CBS, market:"National", show:"Anderson Cooper 360", context:"vaccine". Archive coverage varies by station; use gdelt_list_tv_stations for station IDs, network and market values, and monitoring date ranges.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "gdelt_search_tv"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum timeline points returned per page (default 500, cap 20,000). Larger counts clamp with limitClamp; strict deployments reject them. | |
| 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-name 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. | |
| combined | No | Pool selected stations into one Combined timeline. Normalized values divide pooled matching clips by pooled monitored clips; false keeps separate station series. | |
| stations | No | Station IDs to filter to (e.g. ["CNN", "FOXNEWS", "MSNBC"]) — the stationId values gdelt_list_tv_stations returns, not display labels such as "FOX News". Every supplied ID is forwarded. Alternatively use station:, network:, or quoted market: selectors in query; a selector is required. Obtain network and market values and per-station archive ranges from gdelt_list_tv_stations. | |
| timespan | No | Relative window counting back from now (a number and unit such as d, m, or y). Now is past the end of most stations' monitoring, so for archived periods set startDatetime/endDatetime inside a station's range from gdelt_list_tv_stations. Ignored when startDatetime/endDatetime are set. | |
| 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 | Trailing moving-average width in timesteps, 0–30 (0 or 1 = none). Width N needs N source steps; leading steps cannot produce averages and peaks may appear later. | |
| 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
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| limit | No | Maximum points this page holds — the requested limit, or 20,000 when a larger one was clamped. | |
| notice | No | When smoothing is above 1, that leading steps without a full window have no values and peaks may lag. When the query matched no TV coverage: the resolved timespan window; for each selected station whose monitoring range the window misses, that range and how to search inside it; and how to check station coverage. When a returned series has no station ID, why: GDELT returned it without a station label, or its station catalog did not load or has no entry for the named label — with how to look the ID up. Absent when coverage was returned, smoothing is at most 1, and every series carries its station ID or combined is true. | |
| offset | No | Zero-based offset of this point page. | |
| series | No | Station series represented in this point page. | |
| combined | No | True for one pooled Combined timeline; false for separate station series. | |
| timeRange | No | Date range spanned by this returned point page. Omitted when the page is empty. | |
| limitClamp | No | Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value. | |
| 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. | |
| staleResponse | No | Present only when the refetch of this exact request was refused, failed, or came back empty, and the response is GDELT's stored answer from fetchedAt instead. It holds nothing published after fetchedAt; a relative timespan covers the window ending at fetchedAt, not now. Absent on a live answer. | |
| 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. |