Docs menu

GDELT API endpoint

GDELT Television Show Chart API

Ranks US television shows by how much they covered a topic. At least one `station` is required, and a match is set with `transcript`, `caption`, `concept`, `onscreen_text` or `visual` (with `exclude_` counterparts), optionally limited by `show`, `timespan` or `from` and `to`. Returns shows with a `count`. Omitting the time window searches the archive back to July 2010.

GETapiKey0 credits/requestGDELTgdelt.tvShowChartResponseDoc/gdelt/tv-showchart

Endpoint facts

Method: GET
API path: /gdelt/tv-showchart
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.tvShowChartResponseDoc

GDELT News Monitoring API Try GDELT Television Show Chart API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

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, repeatable) — one or more stations, OR'd together, e.g. station=CNN. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO (ABC, San Francisco), KPIX (CBS, San Francisco), KNTV (NBC, San Francisco). GDELT rejects any request with no station. See gdelt-tv-stationdetails for GDELT's own current list.
show (optional) — limit to an exact show name.
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.

An exclude_* value does not count as a positive term — GDELT rejects a query built from station/exclude_* fields alone ("Queries must have at least one non-negative term."); combine exclusion with at least one non-exclude_* content field.

Notable response behavior:

shows[].count is a percentage of matching results attributed to that show (GDELT's own "top shows by result percentage"), not a raw count — unlike gdelt-tv-stationchart's count, which is a raw integer.
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
A GDELT-side rate limit, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tv-showchart?caption=trump&station=CNN
Items in shows: 431
Fields filled in every checked item: 2

Field	Filled in, of 431 checked	Values in the sample
show	431	“Anderson Cooper 360” and 430 other values
count	431	0 to 7.84, median 0.01

Request parameters

Parameter	Type	Required	Description	Example
transcript	array<string>	No	Search machine-generated speech-to-text transcripts (GDELT's asr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	climate change
caption	array<string>	No	Search human-provided closed captioning (GDELT's cap: operator). Repeatable; multiple values are OR'd together.	trump
concept	array<string>	No	Search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator). Repeatable; multiple values are OR'd together.	/M/0d063v
onscreen_text	array<string>	No	Search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	breaking news
visual	array<string>	No	Search visual object/activity labels from computer vision (GDELT's visual: operator). Repeatable; multiple values are OR'd together.	flood
exclude_transcript	array<string>	No	Exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Repeatable; every value must be absent.	campaign ad
exclude_caption	array<string>	No	Exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Repeatable; every value must be absent.	sanders
exclude_concept	array<string>	No	Exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Repeatable; every value must be absent.	/M/081pw
exclude_onscreen_text	array<string>	No	Exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Repeatable; every value must be absent.	sponsored
exclude_visual	array<string>	No	Exclude clips whose visual labels match this value (GDELT's -visual: operator). Repeatable; every value must be absent.	advertisement
station	array<string>	Yes	Required, repeatable. One or more stations, OR'd together. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO, KPIX, KNTV.	CNN
show	string	No	Limit to an exact show name.	Inside Politics
timespan	string	No	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).	30d
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-07-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-showchart?station=CNN" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "cap:\"trump\" station:CNN",
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=showchart&query=cap%3A%22trump%22+station%3ACNN",
    "fetched_at": "2026-08-20T10:00:00Z",
    "shows": [
      {
        "show": "Anderson Cooper 360",
        "count": 7.8383
      },
      {
        "show": "Erin Burnett OutFront",
        "count": 5.4222
      },
      {
        "show": "CNN Newsroom Live",
        "count": 5.2105
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvShowChartResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TVShowChartResponse	No
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.query	string	No	cap:"trump" station:CNN
data.shows	array	No
data.shows[].count	number	No	7.8383
data.shows[].show	string	No	Anderson Cooper 360
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=showchart&query=cap%3A%22trump%22+station%3ACNN
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-showchart?station=CNN" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More GDELT endpoint docs GDELT News Monitoring API GDELT Context Search API documentation GDELT Search API documentation GDELT Timeline API documentation GDELT Tone Chart API documentation GDELT Television Concept Entities API documentation GDELT Television Search API documentation

Open in Playground Back to group

Docs menu

GDELT API endpoint

GDELT Television Show Chart API

GETapiKey0 credits/requestGDELTgdelt.tvShowChartResponseDoc/gdelt/tv-showchart

Endpoint facts

Method: GET
API path: /gdelt/tv-showchart
Auth: apiKey
Credits: 0 credits/request
Charged on: Successful 2xx responses only
Platform: GDELT
Response schema: #/definitions/gdelt.tvShowChartResponseDoc

GDELT News Monitoring API Try GDELT Television Show Chart API in Playground GDELT API documentation

How this endpoint behaves

Path parameters:

None.

Query parameters:

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, repeatable) — one or more stations, OR'd together, e.g. station=CNN. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO (ABC, San Francisco), KPIX (CBS, San Francisco), KNTV (NBC, San Francisco). GDELT rejects any request with no station. See gdelt-tv-stationdetails for GDELT's own current list.
show (optional) — limit to an exact show name.
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.

Notable response behavior:

shows[].count is a percentage of matching results attributed to that show (GDELT's own "top shows by result percentage"), not a raw count — unlike gdelt-tv-stationchart's count, which is a raw integer.
source_url is the exact upstream GDELT Television 2.0 AI API URL used for the call.
A GDELT-side rate limit, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a 503 upstream error, not a 200 with empty/wrong data.

Sampled response

Request, 14 Oct 2026: GET /gdelt/tv-showchart?caption=trump&station=CNN
Items in shows: 431
Fields filled in every checked item: 2

Field	Filled in, of 431 checked	Values in the sample
show	431	“Anderson Cooper 360” and 430 other values
count	431	0 to 7.84, median 0.01

Request parameters

Parameter	Type	Required	Description	Example
transcript	array<string>	No	Search machine-generated speech-to-text transcripts (GDELT's asr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	climate change
caption	array<string>	No	Search human-provided closed captioning (GDELT's cap: operator). Repeatable; multiple values are OR'd together.	trump
concept	array<string>	No	Search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator). Repeatable; multiple values are OR'd together.	/M/0d063v
onscreen_text	array<string>	No	Search OCR'd onscreen text/chyrons (GDELT's ocr: operator). Repeatable; multiple values are OR'd together. Short phrases only (GDELT caps each at 5 words).	breaking news
visual	array<string>	No	Search visual object/activity labels from computer vision (GDELT's visual: operator). Repeatable; multiple values are OR'd together.	flood
exclude_transcript	array<string>	No	Exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Repeatable; every value must be absent.	campaign ad
exclude_caption	array<string>	No	Exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Repeatable; every value must be absent.	sanders
exclude_concept	array<string>	No	Exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Repeatable; every value must be absent.	/M/081pw
exclude_onscreen_text	array<string>	No	Exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Repeatable; every value must be absent.	sponsored
exclude_visual	array<string>	No	Exclude clips whose visual labels match this value (GDELT's -visual: operator). Repeatable; every value must be absent.	advertisement
station	array<string>	Yes	Required, repeatable. One or more stations, OR'd together. Allowed values: CNN, MSNBC, FOXNEWS, BBCNEWS, KGO, KPIX, KNTV.	CNN
show	string	No	Limit to an exact show name.	Inside Politics
timespan	string	No	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).	30d
from	string	No	Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.	2026-07-01
to	string	No	End of an absolute time window. Same formats as from.	2026-08-19
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-showchart?station=CNN" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "cap:\"trump\" station:CNN",
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=showchart&query=cap%3A%22trump%22+station%3ACNN",
    "fetched_at": "2026-08-20T10:00:00Z",
    "shows": [
      {
        "show": "Anderson Cooper 360",
        "count": 7.8383
      },
      {
        "show": "Erin Burnett OutFront",
        "count": 5.4222
      },
      {
        "show": "CNN Newsroom Live",
        "count": 5.2105
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/gdelt.tvShowChartResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	gdelt.TVShowChartResponse	No
data.fetched_at	string	No	2026-08-20T10:00:00Z
data.query	string	No	cap:"trump" station:CNN
data.shows	array	No
data.shows[].count	number	No	7.8383
data.shows[].show	string	No	Anderson Cooper 360
data.source_url	string	No	https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=showchart&query=cap%3A%22trump%22+station%3ACNN
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
500	Internal Server Error	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/gdelt/tv-showchart?station=CNN" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

GDELT Television Show Chart API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

GDELT Television Show Chart API

Endpoint facts

How this endpoint behaves

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related