When to use this skill
When the user asks about recent news coverage of a topic, event, or keyword — "what's the latest on X", "find articles about Y", or "show me news from country Z" — reach for the GDELT Doc API. It monitors broadcast, print, and web sources in over 100 languages and returns article metadata including source country and language in a single unauthenticated call. For television transcript search with station filtering, use the GDELT TV API instead. For historical event-level time-series data, this is the wrong skill.
Your best first call
curl "https://api.gdeltproject.org/api/v2/doc/doc?query=climate+change&mode=ArtList&maxrecords=10&format=json"
No auth. No key. The query parameter is required and accepts plain keywords, theme filters (theme:ENVIRONMENT), country filters (country:US), and date ranges (date:20260401-20260415). Combine terms with spaces. The mode parameter is required — use ArtList for article metadata. Set maxrecords between 1 and 250 to control volume.
Each article in the articles array provides:
url — link to the original articletitle — headlineseendate — when GDELT indexed it, formatted YYYYMMDDTHHMMSSZdomain — source domain (e.g. bbc.co.uk, is.fi)language — language name (e.g. "Finnish", "Turkish", "English")sourcecountry — country of origin (e.g. "Finland", "Turkey", "United States")
A query for "climate change" returns articles from dozens of countries and languages — GDELT is one of the few free APIs where a single call surfaces multilingual coverage in the same response. The sourcecountry and language fields let you filter further in post-processing without additional requests.
Fallbacks (when the best first call isn't enough)
- Television transcript search →
https://api.gdeltproject.org/api/v2/tv/tv?query=station:BBCNEWS+ukraine&mode=ClipGallery&format=json when the user specifically wants TV broadcast transcripts. Every TV query must include a station identifier (station:BBCNEWS, station:CNN) — bare keyword queries to the TV endpoint return a 400 error.
- Date-constrained searches → append
date:YYYYMMDD for a single day or date:YYYYMMDD-YYYYMMDD for a range to the query parameter, e.g. query=climate+change+date:20260401-20260415.
Pitfalls
- The rate limit is 1 request per 5 seconds — a hard throttle. Two requests within 5 seconds triggers a 429 on the second call.
seendate uses YYYYMMDDTHHMMSSZ format (e.g. 20260407T144500Z), not ISO 8601. The T and Z are literal fixed characters.- The
country: filter in queries requires two-letter ISO country codes (country:US, country:FI), not full names. A query like country:United States returns zero results.
- The TV endpoint rejects queries that lack a
station: filter with a 400 error — you cannot search all TV transcripts by keyword alone.
One-line summary for the user
I can search global news articles by keyword across 100+ languages via GDELT — no auth needed, but rate-limited to 1 request per 5 seconds.
Global Database of Events, Language, and Tone (GDELT) API for querying global news articles and TV transcripts. The GDELT Project monitors the world's broadcast, print, and web news in over 100 languages, providing real-time updates on glob…
SKILL.md source (frontmatter + body)
---
name: search-global-news-articles
description: When the user asks about recent news coverage of a topic, event, or keyword — "latest on X", "articles about Y", "news from country Z" — reach for the GDELT Doc API. Monitors 100+ languages, no auth required.
---
## When to use this skill
When the user asks about recent news coverage of a topic, event, or keyword — "what's the latest on X", "find articles about Y", or "show me news from country Z" — reach for the GDELT Doc API. It monitors broadcast, print, and web sources in over 100 languages and returns article metadata including source country and language in a single unauthenticated call. For television transcript search with station filtering, use the GDELT TV API instead. For historical event-level time-series data, this is the wrong skill.
## Your best first call
```bash
curl "https://api.gdeltproject.org/api/v2/doc/doc?query=climate+change&mode=ArtList&maxrecords=10&format=json"
```
No auth. No key. The `query` parameter is required and accepts plain keywords, theme filters (`theme:ENVIRONMENT`), country filters (`country:US`), and date ranges (`date:20260401-20260415`). Combine terms with spaces. The `mode` parameter is required — use `ArtList` for article metadata. Set `maxrecords` between 1 and 250 to control volume.
Each article in the `articles` array provides:
- `url` — link to the original article
- `title` — headline
- `seendate` — when GDELT indexed it, formatted `YYYYMMDDTHHMMSSZ`
- `domain` — source domain (e.g. `bbc.co.uk`, `is.fi`)
- `language` — language name (e.g. "Finnish", "Turkish", "English")
- `sourcecountry` — country of origin (e.g. "Finland", "Turkey", "United States")
A query for "climate change" returns articles from dozens of countries and languages — GDELT is one of the few free APIs where a single call surfaces multilingual coverage in the same response. The `sourcecountry` and `language` fields let you filter further in post-processing without additional requests.
## Fallbacks (when the best first call isn't enough)
- **Television transcript search** → `https://api.gdeltproject.org/api/v2/tv/tv?query=station:BBCNEWS+ukraine&mode=ClipGallery&format=json` when the user specifically wants TV broadcast transcripts. Every TV query must include a station identifier (`station:BBCNEWS`, `station:CNN`) — bare keyword queries to the TV endpoint return a 400 error.
- **Date-constrained searches** → append `date:YYYYMMDD` for a single day or `date:YYYYMMDD-YYYYMMDD` for a range to the `query` parameter, e.g. `query=climate+change+date:20260401-20260415`.
## Pitfalls
- The rate limit is 1 request per 5 seconds — a hard throttle. Two requests within 5 seconds triggers a 429 on the second call.
- `seendate` uses `YYYYMMDDTHHMMSSZ` format (e.g. `20260407T144500Z`), not ISO 8601. The `T` and `Z` are literal fixed characters.
- The `country:` filter in queries requires two-letter ISO country codes (`country:US`, `country:FI`), not full names. A query like `country:United States` returns zero results.
- The TV endpoint rejects queries that lack a `station:` filter with a 400 error — you cannot search all TV transcripts by keyword alone.
## One-line summary for the user
I can search global news articles by keyword across 100+ languages via GDELT — no auth needed, but rate-limited to 1 request per 5 seconds.