gdelt-research

Researches global news and US television coverage via the Crawlora API — GDELT web-news search/context/timeline/sentiment, plus GDELT Television 2.0 AI's index of US TV transcripts, captions, on-screen text, and visual labels — returning clean JSON. Use when the user wants coverage-volume or sentiment trends over time, cross-outlet news search, sentence-level co-occurrence search, or what US TV news said/showed about a topic — OSINT, media-monitoring, and political/social-science research.

News & TV coverage research (GDELT)

Search and chart global news coverage and US television news via the GDELT Project's own indexes — full-text search, sentence-level context search, coverage/tone timelines, and (for TV) transcripts, captions, on-screen text, and computer-vision labels — all as normalized JSON from the Crawlora API, no scraping.

When to use this skill

• "What's the recent news coverage of X?" / "Search global news for X."
• "How has coverage of X trended over time?" / "Is coverage of X positive or negative?" (timeline + tone/sentiment).
• "What sentences mention X near Y?" (sentence-level co-occurrence, last 72 hours only).
• "What did US TV news say/show about X?" (transcripts, captions, on-screen text).
• "Which TV stations/shows covered X the most?" / "What's trending on TV right now?" (word cloud, station/show comparisons).
• OSINT, media-monitoring, or political/social-science research needing a free, no-auth global news/TV corpus.

Setup (one-time)

• Get a free Crawlora API key (2,000 credits/mo, no card) at https://crawlora.net.
• Set CRAWLORA_API_KEY in the environment before running the helper.
• The helper reads CRAWLORA_API_KEY from the environment and sends requests to https://api.crawlora.net/api/v1. Missing/invalid key → 401.

How it works

Web news:

1. Search — /gdelt/search (query, required; optional country, domain, language, from/to/timespan, sort, maxrecords) searches GDELT's continuously updated global news index.
2. Context — /gdelt/context (query, required; is_quote to scope to quoted text) does sentence-level co-occurrence search — last 72 hours of coverage only.
3. Timeline — /gdelt/timeline (query, metric for volume vs. tone, smooth) returns how coverage volume or tone has trended over time.
4. Tone chart — /gdelt/tonechart (query) returns a sentiment histogram for a query's matching coverage.

US television (GDELT Television 2.0 AI):

5. Search — /gdelt/tv-search (station, required; optional show, caption/transcript/onscreen_text/visual/concept text filters and matching exclude_* negations, day_of_week) searches transcripts, captions, OCR text, and computer-vision visual labels.
6. Timeline / comparisons — /gdelt/tv-timeline (airtime volume over time), /gdelt/tv-showchart (top shows by coverage share), /gdelt/tv-stationchart (cross-station comparison) — same filter params as search, station required.
7. Word cloud — /gdelt/tv-wordcloud (station+channel, both required) returns a frequency-ranked word/label cloud for one match.
8. Reference lists — /gdelt/tv-stationdetails (no params) lists current stations; /gdelt/tv-concept-entities and /gdelt/tv-visual-entities (limit) list GDELT's own Knowledge-Graph concept and computer-vision label catalogs, useful for building valid concept/visual filter values.

Full endpoint list, methods, and params: reference/endpoints.md.

Calling the API

sh

# Global news search:
scripts/crawlora.sh /gdelt/search query="semiconductor export controls" | jq '.'

# Coverage volume trend over time:
scripts/crawlora.sh /gdelt/timeline query="semiconductor export controls" metric=timelinevol | jq '.'

# Sentiment histogram:
scripts/crawlora.sh /gdelt/tonechart query="semiconductor export controls" | jq '.'

# US TV: search one station's coverage:
scripts/crawlora.sh /gdelt/tv-search station=CNN show="Erin Burnett OutFront" | jq '.'

# US TV: current station list:
scripts/crawlora.sh /gdelt/tv-stationdetails | jq '.'

Use scripts/crawlora.sh for all requests; it keeps the API key out of command-line arguments.

Endpoint reference

See reference/endpoints.md for every GDELT web-news and Television 2.0 AI endpoint this skill uses.

Examples

• Media narrative tracking: /gdelt/timeline (volume) + /gdelt/tonechart (sentiment) for the same query to see both how much and how favorably a topic is covered over time.
• Cross-medium check: the same query through /gdelt/search (web news) and /gdelt/tv-search (TV) to compare print/online vs. broadcast framing.
• Breaking-story monitoring: /gdelt/context for sentence-level co-occurrence in the last 72 hours — catches emerging framing before a full-timeline trend is visible.
• TV coverage-share research: /gdelt/tv-showchart or /gdelt/tv-stationchart to see which shows/stations are driving coverage of a topic.

Notes & limits

• Credits / pay-on-success: billed only on 2xx; free tier 2,000 credits/mo. Key at https://crawlora.net.
• Public data only — GDELT's own public indexes; no authentication possible or needed upstream.
• Security: key lives in CRAWLORA_API_KEY only — never hardcode, query-param, or commit it.
• /gdelt/context only covers the last 72 hours — use /gdelt/search or the timeline/tone endpoints for anything further back.
• Every TV endpoint requires station (/gdelt/tv-wordcloud also requires channel) — list valid values via /gdelt/tv-stationdetails first if unsure.
• timespan and from/to are alternative ways to scope a date range — don't mix them; pick one.