GDELT Television Word Cloud API

Endpoint facts

Method

GET

API path

/gdelt/tv-wordcloud

Auth

apiKey

Credits

0 credits/request

Charged on

Successful 2xx responses only

Platform

GDELT

Response schema

#/definitions/gdelt.tvWordCloudResponseDoc

How this endpoint behaves

Path parameters:

• None.

Query parameters:

• channel (required) — which match channel to build the word cloud from. Allowed values: transcript (GDELT's WordCloudAsr mode), caption (WordCloudCap), concept (WordCloudCapNLP — Google Knowledge Graph concept labels, not MID codes), onscreen_text (WordCloudOCR), visual (WordCloudVisual). This selects which mode is called; the query below can still match on any combination of channels regardless of channel.
• transcript (optional, repeatable) — search machine-generated speech-to-text transcripts (GDELT's asr: operator). Multiple values are OR'd together. Short phrases only — GDELT caps each at 5 words.
• caption (optional, repeatable) — search human-provided closed captioning (GDELT's cap: operator). Multiple values are OR'd together.
• concept (optional, repeatable) — search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator), e.g. /M/0d063v. Multiple values are OR'd together. See gdelt-tv-concept-entities for GDELT's own catalog of valid MID codes.
• onscreen_text (optional, repeatable) — search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Multiple values are OR'd together. Short phrases only — GDELT caps each at 5 words.
• visual (optional, repeatable) — search visual object/activity labels from computer vision (GDELT's visual: operator), e.g. VOLCANO, POLICE. Multiple values are OR'd together. See gdelt-tv-visual-entities for GDELT's own catalog of valid labels.
• exclude_transcript (optional, repeatable) — exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Every value must be absent.
• exclude_caption (optional, repeatable) — exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Every value must be absent.
• exclude_concept (optional, repeatable) — exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Every value must be absent.
• exclude_onscreen_text (optional, repeatable) — exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Every value must be absent.
• exclude_visual (optional, repeatable) — exclude clips whose visual labels match this value (GDELT's -visual: operator). Every value must be absent.
• station (required) — station to search. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO (ABC, San Francisco), KPIX (CBS, San Francisco), KNTV (NBC, San Francisco). See gdelt-tv-stationdetails for GDELT's own current list.
• show (optional) — limit to an exact show name.
• day_of_week (optional) — limit to a day of week, 0 (Sunday) through 7 (Saturday), PST.
• timespan (optional) — relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. Omit both for GDELT's full archive (auto-resolution, back to July 6, 2010).
• from (optional) — start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.
• to (optional) — end of an absolute time window. Same formats as from.

At least one of transcript/caption/concept/onscreen_text/visual is required in addition to station — GDELT rejects a station-only or station-plus-show-only query. An exclude_* value does not count as that positive term; combine exclusion with at least one non-exclude_* field.

Notable response behavior:

• words[].count is a percentage relative to the single most frequent entry (always 100), not a raw occurrence count.
• GDELT computes this from up to the 200 most relevant matching clips and returns up to roughly 200 words/labels — there is no client-controllable result size; a limit-style parameter is not offered because GDELT's own maxrecords is silently ignored for this mode.
• channel in the response echoes the requested channel.
• query is the exact upstream query string built from the request (excluding channel, mode, and format, which route the request but aren't part of GDELT's own query language).
• source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
• A GDELT-side rate limit, a query with no content-matching term, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a 400/503 upstream error, not a 200 with empty/wrong data. A legitimate zero-match query returns 200 with an empty words array.

Sampled response

Request, 14 Oct 2026

GET /gdelt/tv-wordcloud?caption=trump&channel=caption&station=CNN

Items in words

262

Fields filled in every checked item

2

Shared guides

Related