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

1. Build a query in GDELT DSL (the user's term, optionally with operators like

domain:bloomberg.com, sourcelang:eng).

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

1. 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 in meta.window so 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-records cap 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-news for curated equity-specific newsfeed (Chinese-language UX).
• sec-edgar for primary-source filings as the contrast to media narrative.
• fred for macro data referenced in the narrative.