GDELT

Search US television news coverage (transcripts, captions, OCR, visual labels)

Searches GDELT's US television news index on one required station (CNN, MSNBC, FOXNEWS, BBCNEWS, KGO, KPIX or KNTV). Match on transcript, caption, concept, onscreen_text or visual, with matching exclude_ options. Returns up to maxrecords clips (default 50, max 3000) with show, station, timing, caption, transcript, onscreen text and clip URL. Results lag 24 to 48 hours.

get/gdelt/tv-search

Request

  • Base URL: https://api.crawlora.net/api/v1
  • URL: https://api.crawlora.net/api/v1/gdelt/tv-search
  • Auth: API key in header x-api-key

Query parameters

transcriptstring[]

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).

captionstring[]

Search human-provided closed captioning (GDELT's cap: operator). Repeatable; multiple values are OR'd together.

conceptstring[]

Search Google Knowledge Graph concepts extracted from captioning, by MID code (GDELT's capnlp: operator). Repeatable; multiple values are OR'd together.

onscreen_textstring[]

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).

visualstring[]

Search visual object/activity labels from computer vision (GDELT's visual: operator). Repeatable; multiple values are OR'd together.

exclude_transcriptstring[]

Exclude clips whose speech-to-text transcript matches this value (GDELT's -asr: operator). Repeatable; every value must be absent.

exclude_captionstring[]

Exclude clips whose closed captioning matches this value (GDELT's -cap: operator). Repeatable; every value must be absent.

exclude_conceptstring[]

Exclude clips whose extracted concepts match this MID code (GDELT's -capnlp: operator). Repeatable; every value must be absent.

exclude_onscreen_textstring[]

Exclude clips whose OCR'd onscreen text matches this value (GDELT's -ocr: operator). Repeatable; every value must be absent.

exclude_visualstring[]

Exclude clips whose visual labels match this value (GDELT's -visual: operator). Repeatable; every value must be absent.

station'CNN' | 'MSNBC' | 'FOXNEWS' | 'BBCNEWS' | 'KGO' | 'KPIX' | 'KNTV' required

Station to search.

showstring

Limit to an exact show name.

day_of_weekinteger

Limit to a day of week, 0 (Sunday) through 7 (Saturday), PST.

timespanstring

Relative time window ending now, e.g. 1h, 7d, 3m, 1y. Cannot be combined with from/to. GDELT's TV archive starts July 6, 2010.

fromstring

Start of an absolute time window. Accepts YYYY-MM-DD, RFC3339, or GDELT's raw YYYYMMDDHHMMSS. Cannot be combined with timespan.

tostring

End of an absolute time window. Same formats as from.

sort'relevance' | 'datedesc' | 'dateasc'

Result order.

maxrecordsinteger

Rows to return. GDELT's own hard cap is 3000 for this endpoint; there is no pagination cursor beyond it.

Headers

x-api-keystring required

API key required

Response

OK

codeinteger
msgstring

Example response

{
  "code": 200,
  "data": {
    "clips": [
      {
        "caption": "climate",
        "caption_concepts": "/M/0d063v",
        "clip_url": "https://archive.org/details/CNNW_20190503_160000_Inside_Politics/start/3656",
        "matched_at": "2019-05-03T17:00:56Z",
        "onscreen_text": "BREAKING NEWS: SEA LEVELS RISING",
        "show": "Inside Politics",
        "show_start_at": "2019-05-03T16:00:00Z",
        "station": "cnn",
        "thumbnail_url": "http://data.gdeltproject.org/televisionexplorer/thumbnails/CNNW_20190503_160000_Inside_Politics-003656.jpg",
        "transcript": "climate change the",
        "visual_entities": [
          "person",
          "news",
          "weather"
        ]
      }
    ],
    "count": 3,
    "fetched_at": "2026-08-20T10:00:00Z",
    "maxrecords": 50,
    "query": "cap:\"climate change\" station:CNN",
    "sort": "relevance",
    "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&maxrecords=50&mode=clipgallery&query=cap%3A%22climate+change%22+station%3ACNN",
    "station": "CNN"
  },
  "msg": "OK"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.