gdelt
Response language: match user input.
⚠️ GDELT is a rolling recent-window API, not a historical event archive. Time windows are anchored to absolute timestamps (UTC) for reproducibility — the same query asked tomorrow will return different results.
⚠️ 5-second throttle between requests (enforced). Plan batches accordingly.
When to use
Trigger phrases:
- 全球新闻 / 全球事件 / 多语种新闻
- 媒体 tone / sentiment trend / 国际关系
- geopolitical / event tone
- GDELT
Useful for "what is the world saying about X right now" — i.e. retrieving articles from non-English / non-financial sources that don't surface in Longbridge's curated newsfeed.
Workflow
- Build a query in GDELT DSL (the user's term, optionally with operators like
domain:bloomberg.com,sourcelang:eng). - Pick a mode:
artlist— list of articles (default).timelinetone— per-15-min tone time series (-10 = very negative, +10 = very positive).timelinevol/timelinevolinfo— article volume over time.tonechart— tone histogram.
- Specify the window — prefer
--start/--end(absolute), fall back to--timespan. The script converts relative timespans to absolute timestamps before the call and echoes them inmeta.windowso the journal can be re-run.
CLI examples
bash# Articles about Nvidia in the last 24h python3 .claude/skills/gdelt/scripts/doc.py "Nvidia" # 7-day window, English + Chinese articles about TSMC python3 .claude/skills/gdelt/scripts/doc.py "TSMC OR \"Taiwan Semiconductor\"" --timespan 7d --lang eng,zho # Tone timeline for Federal Reserve over 30 days python3 .claude/skills/gdelt/scripts/doc.py "Federal Reserve" --mode timelinetone --timespan 30d # Absolute window python3 .claude/skills/gdelt/scripts/doc.py "AI chips" --start 20260501000000 --end 20260528000000
Output shape (artlist)
json{ "data": [ { "url": "https://...", "title": "...", "seendate": "20260527T161500Z", "domain": "...", "language": "English", "sourcecountry": "United States", "socialimage": "..." } ], "meta": { "mode": "artlist", "query": "Nvidia", "window": { "start": "20260527071804", "end": "20260528071804" }, "max_records": 75 }, "ok": true }
Output shape (timelinetone)
json{ "ok": true, "data": [ {"date": "20260520T000000Z", "value": 1.42}, {"date": "20260520T001500Z", "value": 1.05}, ... ], "meta": {"mode": "timelinetone", ...} }
Error handling
| Exit code | Meaning | LLM action |
|---|---|---|
| 0 | Success | Parse data. |
| 1 | Invalid args (e.g. bad timespan / lang) | Read hint. |
| 3 | HTTP 4xx / non-JSON response | If body contains "Please limit requests", the throttle was tripped — wait and retry. |
| 4 | Network | Suggest retry. |
Known limitations
- 5-second minimum between requests; batch tone + artlist queries must be sequenced.
--max-recordscap is 250.- GDELT's tone metric is a heuristic — useful for direction-of-narrative, not ground truth.
- Results are not cached (window-sensitive).
Related skills
longbridge-newsfor curated equity-specific newsfeed (Chinese-language UX).sec-edgarfor primary-source filings as the contrast to media narrative.fredfor macro data referenced in the narrative.
