Media and narrative monitoring
Usa los endpoints de GDELT para convertir media and narrative monitoring en solicitudes API repetibles con inputs documentados y respuestas JSON.
Turn the GDELT Project's continuously updated global news index (65+ languages, reindexed roughly every 15 minutes) into structured JSON — keyword and boolean article search, coverage-volume or sentiment timelines, a tone histogram, and sentence-level context search for verifying how two topics are actually discussed together. Also covers GDELT's Television 2.0 AI index of US TV news broadcasts (ABC/CBS/NBC evening news since July 2010, CNN's full archive) — transcript/caption/OCR/visual-label search, station and show comparisons, airtime timelines, and word clouds. Keyless upstream, no login required.
Search the GDELT Project's global news index and chart coverage volume or sentiment over time as structured JSON.
Familias de endpoints
6
Parámetros documentados
128
Ejemplos
12
Snapshot en vivo del catálogo
Endpoints activos
12
Métodos
GET
Parámetros obligatorios
22
Referencias de esquema
12
{
"platform": "GDELT",
"endpoint": "gdelt-search",
"method": "GET",
"path": "/gdelt/search",
"auth": "apiKey"
}Casos de uso
Search the GDELT Project's global news index and chart coverage volume or sentiment over time as structured JSON.
Usa los endpoints de GDELT para convertir media and narrative monitoring en solicitudes API repetibles con inputs documentados y respuestas JSON.
Usa los endpoints de GDELT para convertir sentiment and coverage-volume tracking en solicitudes API repetibles con inputs documentados y respuestas JSON.
Usa los endpoints de GDELT para convertir geopolitical and market-event research en solicitudes API repetibles con inputs documentados y respuestas JSON.
Usa los endpoints de GDELT para convertir us tv news coverage comparison en solicitudes API repetibles con inputs documentados y respuestas JSON.
Ejecución gestionada
Cada cifra de abajo se lee directamente del catálogo de endpoints en vivo de GDELT — 12 endpoints, 128 parámetros de solicitud documentados y 12 esquemas de respuesta publicados — el mismo catálogo contra el que corren Docs y Playground.
12 documented GDELT endpoints, grouped into 12 request families — Context, Search and Timeline, plus 9 more.
128 request parameters are documented across those GDELT endpoints, 22 of them required — the full input contract is public before you write any integration code.
12 of the 12 GDELT endpoints ship a recorded example response, and 12 carry a documented response schema — you can code against the real JSON before the first request.
GDELT endpoints document their error responses (400, 500 and 503) alongside the success schema, so a block, a rate limit, or a missing record comes back as a typed error rather than silently empty data.
12 hosted MCP tools back the GDELT endpoints, so an agent can call the same routes with the same parameters and the same JSON contract, with no custom glue.
Mapa de cobertura
/gdelt/context
/gdelt/search
/gdelt/timeline
/gdelt/tonechart
/gdelt/tv-concept-entities
/gdelt/tv-search
Catálogo de endpoints
/gdelt/searchSearches global news coverage indexed by GDELT for the required `query`, which accepts quoted phrases, `(a OR b)`, `theme:`, `tone<N` and `domain:`. Narrow with `country`, `language`, `domain`, and `timespan` or `from` and `to` (about the last 3 months are indexed). Returns up to `maxrecords` articles (default 75, max 250) with title, URL, domain, language, source country and `seen_at`.
Notas de la respuesta
- `count` is the number of articles actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error). - `source_url` is the exact upstream GDELT DOC API URL used for the call. - A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_search
/gdelt/timelineReturns how coverage of the required GDELT `query` changes over time, as dated points. `metric` picks `volume` (the default, share of monitored articles), `volume_raw` (matching article count), `tone` (average sentiment), or `lang` and `country` for one series per language or country. Filter with `country`, `language`, `domain`, `timespan` or `from` and `to`; `smooth` runs 0 to 30 (default 0).
Notas de la respuesta
- `series` contains exactly one entry for `metric=volume`/`volume_raw`/ `tone`; for `metric=lang`/`country` it contains one entry per language/country GDELT found in the matching coverage. Each entry's `points` is chronologically ordered. - `source_url` is the exact upstream GDELT DOC API URL used for the call. - A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_timeline
/gdelt/tonechartReturns a sentiment histogram for the required GDELT `query`: one bin per integer tone value, each with an article `count` and a short sample of top articles with title and URL. Filter with `country`, `language`, `domain`, and `timespan` or `from` and `to`. A tone value with no matching articles is absent rather than returned with a zero count.
Notas de la respuesta
- `bins` is ordered by GDELT's own upstream order (not guaranteed sorted by `bin`); a bin with zero matching articles for that tone value is simply absent from the array, not returned with `count: 0`. - `top_articles` is a short, GDELT-selected sample per bin, not an exhaustive list — use [gdelt-search](gdelt-search.md) with a `tone<N`/ `tone>N` query clause for the full article list at a given sentiment range. - `source_url` is the exact upstream GDELT DOC API URL used for the call. - A GDELT-side rate limit or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_tonechart
/gdelt/contextSearches the last 72 hours of GDELT-monitored news for sentences where every term of the required `query` appears together. Returns up to `maxrecords` rows (default 75, max 200), each with the matching sentence, its surrounding context, title, URL, domain, language and an `is_quote` flag. Filter with `domain`, `language`, `is_quote`, `timespan` or `from` and `to`, and order with `sort`.
Notas de la respuesta
- `sentence` is the single matching sentence (GDELT returns at most one matching sentence per article); `context` is the surrounding paragraph. - `count` is the number of articles actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error). - `source_url` is the exact upstream GDELT Context API URL used for the call. - A GDELT-side rate limit, a timespan/date range GDELT itself rejects as out of its 72-hour window, or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data. An out-of-range `timespan` is instead rejected client-side as a `400` before ever reaching GDELT (see the `timespan` note above); an out-of-range `from`/`to` combination is not independently validated client-side and falls through to GDELT's own `503`-classified rejection.
Herramienta MCP gdelt_context
/gdelt/tv-searchSearches 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.
Notas de la respuesta
- `matched_at` is the exact timestamp of the matched moment within the broadcast; `show_start_at` is when the containing show began. - `visual_entities` is returned as a list. - `count` is the number of clips actually returned (0 is a valid, legitimate "no matches" result, distinct from an upstream error). - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - A GDELT-side rate limit, an all-too-common ASR/caption/OCR phrase, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_tv_search
/gdelt/tv-timelineReturns the amount of US television news airtime matching the supplied query over time, using GDELT Television 2.0 AI timeline-volume data. A station is required. Supports the same caption, transcript, concept, and visual match operators as gdelt-tv-search; coverage and processing-delay caveats are documented there.
Notas de la respuesta
- `series` normally contains exactly one entry; GDELT's Television 2.0 AI timeline doesn't name its series the way DOC 2.0's does (the `series` field is empty), but `points` is still chronologically ordered. - GDELT auto-selects a date resolution (hour/day/week/month/year) based on the requested window's length; there is no `smooth` parameter for this endpoint (unlike [gdelt-timeline](gdelt-timeline.md)). - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - A GDELT-side rate limit, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_tv_timeline
/gdelt/tv-stationchartCompares how much each US television station covered a topic. At least one `station` is required, and several are compared side by side. A match is set with `transcript`, `caption`, `concept`, `onscreen_text` or `visual` (with `exclude_` counterparts), optionally limited by `show`, `timespan` or `from` and `to`. Returns each station with a `count`.
Notas de la respuesta
- `stations[].count` is a raw article/clip-match count, not a percentage (unlike [gdelt-tv-showchart](gdelt-tv-showchart.md)'s `count`). - A single station still works, but returns only that one station's count — the endpoint is most useful with 2+ stations. - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - A GDELT-side rate limit, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_tv_stationchart
/gdelt/tv-showchartRanks US television shows by how much they covered a topic. At least one `station` is required, and a match is set with `transcript`, `caption`, `concept`, `onscreen_text` or `visual` (with `exclude_` counterparts), optionally limited by `show`, `timespan` or `from` and `to`. Returns shows with a `count`. Omitting the time window searches the archive back to July 2010.
Notas de la respuesta
- `shows[].count` is a **percentage** of matching results attributed to that show (GDELT's own "top shows by result percentage"), not a raw count — unlike [gdelt-tv-stationchart](gdelt-tv-stationchart.md)'s `count`, which is a raw integer. - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - A GDELT-side rate limit, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a `503` upstream error, not a `200` with empty/wrong data.
Herramienta MCP gdelt_tv_showchart
/gdelt/tv-wordcloudReturns a frequency-ranked word cloud for US television coverage. `channel` is required and picks what is counted: `transcript`, `caption`, `concept`, `onscreen_text` or `visual`; `station` is also required. Match with the same channel options (with `exclude_` counterparts) and limit by `show`, `day_of_week`, `timespan` or `from` and `to`. Each word has a `label` and `count`.
Notas de la respuesta
- `words[].count` is a percentage relative to the single most frequent entry (always `100`), not a raw occurrence count. - GDELT computes this from up to the 200 most relevant matching clips and returns up to roughly 200 words/labels — there is no client-controllable result size; a `limit`-style parameter is not offered because GDELT's own `maxrecords` is silently ignored for this mode. - `channel` in the response echoes the requested channel. - `query` is the exact upstream query string built from the request (excluding `channel`, `mode`, and `format`, which route the request but aren't part of GDELT's own query language). - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - A GDELT-side rate limit, a query with no content-matching term, a date outside the archive's range, or an unrecognized/malformed upstream response surfaces as a `400`/`503` upstream error, not a `200` with empty/wrong data. A legitimate zero-match query returns `200` with an empty `words` array.
Herramienta MCP gdelt_tv_wordcloud
/gdelt/tv-stationdetailsLists the television stations GDELT currently monitors, each with its `id`, short `label` and a `label_long` that includes its coverage dates. Use the ids as `station` in the GDELT TV endpoints. It takes no parameters.
Notas de la respuesta
- `stations` is the complete list GDELT itself currently monitors. As of 2026-08-20 that's `CNN`, `MSNBC`, `FOXNEWS`, `BBCNEWS`, `KGO` (ABC, San Francisco), `KPIX` (CBS, San Francisco), `KNTV` (NBC, San Francisco) — but treat this endpoint's own live output as the source of truth, not this list, since GDELT can add stations over time. - `label` is a short display name (e.g. `ABC`); `label_long` includes the station's coverage window (e.g. `ABC (KGO) (7/15/2010 - Now)`). - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - Cached for longer (a few hours) than the rest of this platform, since this is reference data that changes on the order of "GDELT adds a new station," not per-query.
Herramienta MCP gdelt_tv_stationdetails
/gdelt/tv-concept-entitiesLists the Google Knowledge Graph concept entities GDELT recognises in US television captioning, most frequent first, up to `limit` entries (default 100, max 10000). Each has a display `label` and a `mid` code. Pass the `mid`, not the label, as `concept` to the GDELT TV search and chart endpoints. The list does not depend on any query.
Notas de la respuesta
- `entities` is query-independent — the same list every call returns, regardless of any other GDELT endpoint's query/station/time-range state. Only `limit` changes what comes back. - `entities[].mid` is the exact string to pass as `concept` on gdelt-tv-search/gdelt-tv-timeline/gdelt-tv-stationchart/gdelt-tv-showchart. `entities[].label` is for display only — GDELT does not accept the label itself as a search value. - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - Cached for longer (a few hours) than the rest of this platform, since this is reference data that only shifts as GDELT's own recognized concept vocabulary grows.
Herramienta MCP gdelt_tv_concept_entities
/gdelt/tv-visual-entitiesLists the computer-vision object and activity labels GDELT recognises in US television video, most frequent first, up to `limit` entries (default 100, max 10000). The label itself is the value to pass as `visual` to the GDELT TV search and chart endpoints. The list does not depend on any query.
Notas de la respuesta
- `entities` is query-independent — the same list every call returns, regardless of any other GDELT endpoint's query/station/time-range state. Only `limit` changes what comes back. - `entities[].label` is the exact string to pass as `visual` on gdelt-tv-search/gdelt-tv-timeline/gdelt-tv-stationchart/gdelt-tv-showchart — unlike [gdelt-tv-concept-entities](gdelt-tv-concept-entities.md)'s `mid`/`label` pair, visual labels have no separate code; the label itself is the search value. - `source_url` is the exact upstream GDELT Television 2.0 AI API URL used for the call. - Cached for longer (a few hours) than the rest of this platform, since this is reference data that only shifts as GDELT's own recognized visual vocabulary grows.
Herramienta MCP gdelt_tv_visual_entities
APIs relacionadas
Business & Market Intelligence
Turn public GitHub ecosystem signals into structured data for developer-market research, open-source intelligence, recruiting, and AI-agent workflows.
Business & Market Intelligence
Collect public TrustMRR startup marketplace and leaderboard data as normalized JSON for startup research, SaaS discovery, and market intelligence workflows.
Business & Market Intelligence
Add website and competitive intelligence signals from SimilarWeb to research pipelines.
Cómo hacer scraping de GDELT
GDELT publishes a free, keyless public JSON API for its global news index and its Television 2.0 AI index of US TV news broadcasts — Crawlora's 12 GDELT endpoints normalize both into consistent JSON, with the same query syntax across search, timeline, tone chart, and context, plus station/show comparisons and word clouds for TV.
Send a query with GDELT's own operators — quoted phrases, boolean OR, theme:, tone<N/tone>N, domain: — to gdelt-search for a normalized article list.
Use gdelt-timeline for a coverage-volume or average-sentiment series, optionally broken down by source language or country.
Use gdelt-tonechart for a point-in-time tone histogram with representative articles per bin.
Use gdelt-context to find the actual sentences where every query term co-occurs, within the last 72 hours.
Send a query to gdelt-tv-search for matching moments across ABC/CBS/NBC evening news (since July 2010) and CNN's full archive, searched across transcripts, closed captions, OCR'd onscreen text, and visual labels — returns clip timecodes and an Internet Archive link.
Use gdelt-tv-stationchart to compare a query's coverage across requested stations (e.g. CNN vs. MSNBC vs. Fox News), or gdelt-tv-showchart for the top shows covering it, as a share of matching results.
Use gdelt-tv-stationdetails for the authoritative station list, gdelt-tv-concept-entities for Knowledge Graph concept codes, and gdelt-tv-visual-entities for computer-vision object/activity labels — all three feed the station/concept/visual parameters on the other TV endpoints.
Preguntas frecuentes
Send a query — with optional country, language, domain, and time-window filters — to Crawlora's /gdelt/search endpoint and get a normalized article list back, sourced from GDELT's continuously reindexed monitoring index.
GDELT's own upstream is keyless and credential-free; you only need your Crawlora API key to call these endpoints.
Yes — /gdelt/timeline returns a coverage-volume or average-sentiment time series for a query, and /gdelt/tonechart returns a point-in-time sentiment histogram.
GDELT is a single-maintainer academic research project, not a commercial SLA-backed service — treat availability as best-effort and expect occasional rate limiting. Crawlora prices these endpoints at 0 credits per request for that reason.
Yes — /gdelt/tv-search covers GDELT's Television 2.0 AI index of ABC/CBS/NBC evening news since July 2010 and CNN's full archive, searchable across transcripts, closed captions, OCR'd onscreen text, and computer-vision visual labels. Coverage is limited to those four US stations, and results carry a 24-48 hour processing delay.
Yes — /gdelt/tv-stationchart compares result counts across requested stations for a query, and /gdelt/tv-showchart returns the top shows by coverage share. Both require at least one station, taken from /gdelt/tv-stationdetails's own station list.