Get GDELT TV Context
gdelt_get_tv_contextGet the top co-occurring words and phrases from TV news clips matching a query — the vocabulary framing a topic on television. Returns the most frequent non-stopword terms with relative frequency scores (0–100, where 100 = the query term itself). Terms and scores come from GDELT's relevance-ranked sample of matching clips, documented as the 200 most relevant, not all matching coverage — compare windows or stations with a separate, narrower call for each. Use to understand narrative framing, identify related concepts mentioned alongside a topic, or generate follow-up search terms. Returns 25 terms by default, with count pages up to 25,000 terms. Archive coverage varies by station; check gdelt_list_tv_stations for each station’s monitoring date range.
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_get_tv_context"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum score-sorted terms returned per page (default 25, cap 25,000). Larger counts clamp with limitClamp; strict deployments reject them. | |
| query | Yes | Search query for TV transcript content. Same TV operators as gdelt_search_tv: station:CNN, network:CBS, market:"National", show:"Anderson Cooper", context:"vaccine". | |
| offset | No | Zero-based term offset in descending score order. Use nextOffset with the same query inputs for the next page. | |
| stations | No | Station IDs to filter to (e.g. ["CNN", "FOXNEWS"]) — the stationId values gdelt_list_tv_stations returns, not display labels such as "FOX News". 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. | |
| 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. Check station monitoring dates with gdelt_list_tv_stations. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| words | No | Co-occurring terms from GDELT's relevance-ranked sample of matching clips, documented as the 200 most relevant, not all matching coverage, sorted by score descending. | |
| notice | No | On every non-empty result, that terms and scores come from GDELT's relevance-ranked sample of matching clips, documented as the 200 most relevant, not all matching coverage — compare windows or stations with a separate, narrower call for each. When no clips matched, so there is no vocabulary to report: 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 broaden the query or check station monitoring dates. | |
| offset | No | Zero-based offset of this term page. | |
| truncated | No | True when more terms remain after this page; use nextOffset to retrieve them. | |
| 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 of the next term page; absent on the final page. | |
| totalTerms | No | Total co-occurring terms before pagination; never a clip count. | |
| 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. | |
| effectiveQuery | No | Echoed query string for use in follow-up calls. |