Media and narrative monitoring
Use GDELT endpoints to turn media and narrative monitoring into repeatable API requests with documented inputs and JSON responses.
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.
Endpoint families
6
Documented params
128
Examples
12
Live catalog snapshot
Active endpoints
12
Methods
GET
Required params
22
Schema refs
12
{
"platform": "GDELT",
"endpoint": "gdelt-search",
"method": "GET",
"path": "/gdelt/search",
"auth": "apiKey"
}Use cases
Search the GDELT Project's global news index and chart coverage volume or sentiment over time as structured JSON.
Use GDELT endpoints to turn media and narrative monitoring into repeatable API requests with documented inputs and JSON responses.
Use GDELT endpoints to turn sentiment and coverage-volume tracking into repeatable API requests with documented inputs and JSON responses.
Use GDELT endpoints to turn geopolitical and market-event research into repeatable API requests with documented inputs and JSON responses.
Use GDELT endpoints to turn us tv news coverage comparison into repeatable API requests with documented inputs and JSON responses.
Managed execution
Crawlora's GDELT API is designed around GDELT's own data surface, not a generic fetch endpoint — combining endpoint-specific request logic, managed infrastructure, parsing, normalization, billing, and Playground-tested examples.
Request behavior for GDELT endpoints is tuned to the platform's own response shapes and edge cases.
Supported GDELT endpoints can use managed proxy routing to improve reliability and reduce infrastructure work.
Dynamic GDELT pages can be routed through managed browser instances where JavaScript rendering is required.
Challenge pages and unusable GDELT responses are detected and surfaced clearly, not silently returned as empty data.
GDELT results are returned as documented JSON instead of raw HTML.
Test the same GDELT route from Docs and Playground before production integration.
Coverage map
These cards are generated from the active endpoint catalog, so the landing page reflects the same API surface used by Docs and Playground.
/gdelt/context
/gdelt/search
/gdelt/timeline
/gdelt/tonechart
/gdelt/tv-concept-entities
/gdelt/tv-search
Endpoint catalog
/gdelt/searchSearch the GDELT Project's continuously updated global news
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "climate change", "sort": "relevance", "maxrecords": 75, "count": 1, "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&maxrecords=75&mode=artlist&query=climate+change", "fetched_at": "2026-08-20T10:00:00Z", "articles": [ { "url": "https://www.example.com/news/climate-report", "title": "Climate report warns of rising sea levels", "seen_at": "2026-08-19T23:00:00Z", "domain": "example.com", "language": "English", "source_country": "United States", "social_image_url": "https://www.example.com/images/social.jpg" } ] } } ```
/gdelt/timelineReturn how a query's global news coverage has trended over
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "climate change", "metric": "volume", "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=timelinevol&query=climate+change", "fetched_at": "2026-08-20T10:00:00Z", "series": [ { "series": "climate change", "points": [ { "date": "2026-08-13T00:00:00Z", "value": 0.42 }, { "date": "2026-08-14T00:00:00Z", "value": 0.51 } ] } ] } } ```
/gdelt/tonechartReturn a sentiment (tone) histogram for a query's matching
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "climate change", "source_url": "https://api.gdeltproject.org/api/v2/doc/doc?format=json&mode=tonechart&query=climate+change", "fetched_at": "2026-08-20T10:00:00Z", "bins": [ { "bin": -5, "count": 12, "top_articles": [ { "url": "https://www.example.com/news/climate-report", "title": "Climate report warns of rising sea levels" } ] } ] } } ```
/gdelt/contextSearch recent (last 72 hours) GDELT-monitored news for
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "climate change", "sort": "relevance", "maxrecords": 75, "count": 1, "source_url": "https://api.gdeltproject.org/api/v2/context/context?format=json&maxrecords=75&mode=artlist&query=climate+change×pan=24h", "fetched_at": "2026-08-20T10:00:00Z", "articles": [ { "url": "https://www.example.com/news/climate-report", "title": "Climate report warns of rising sea levels", "seen_at": "2026-08-19T23:00:00Z", "domain": "example.com", "language": "ENGLISH", "social_image_url": "https://www.example.com/images/social.jpg", "is_quote": false, "sentence": "Coastal cities face rising seas driven by accelerating climate change.", "context": "The report, released Tuesday, warns that coastal cities face rising seas driven by accelerating climate change. Officials called for immediate action." } ] } } ```
/gdelt/tv-searchSearch GDELT's Television 2.0 AI index of US television news
Response notes
- `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 a normalized list (GDELT's own upstream field is a comma-separated string). - `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "cap:\"climate change\" station:CNN", "station": "CNN", "sort": "relevance", "maxrecords": 50, "count": 1, "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&maxrecords=50&mode=clipgallery&query=cap%3A%22climate+change%22+station%3ACNN", "fetched_at": "2026-08-20T10:00:00Z", "clips": [ { "station": "cnn", "show": "Inside Politics", "show_start_at": "2019-05-03T16:00:00Z", "matched_at": "2019-05-03T17:00:56Z", "transcript": "climate change the", "caption": "climate", "onscreen_text": "SWEEPING PLAN LIVE", "visual_entities": ["person", "news", "facial expression"], "clip_url": "https://archive.org/details/CNNW_20190503_160000_Inside_Politics/start/3656", "thumbnail_url": "http://data.gdeltproject.org/televisionexplorer/thumbnails/CNNW_20190503_160000_Inside_Politics-003656.jpg" } ] } } ```
/gdelt/tv-timelineReturn how much airtime a query's matching US television
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "cap:\"trump\" station:CNN", "station": "CNN", "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?enddatetime=20220831000000&format=json&mode=timelinevol&query=cap%3A%22trump%22+station%3ACNN&startdatetime=20220801000000", "fetched_at": "2026-08-20T10:00:00Z", "series": [ { "series": "", "points": [ { "date": "2022-08-01T12:00:00Z", "value": 76 }, { "date": "2022-08-02T12:00:00Z", "value": 170 } ] } ] } } ```
/gdelt/tv-stationchartReturn a result-count comparison across the requested
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "cap:\"trump\" (station:CNN OR station:MSNBC OR station:FOXNEWS)", "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=stationchart&query=cap%3A%22trump%22+%28station%3ACNN+OR+station%3AMSNBC+OR+station%3AFOXNEWS%29", "fetched_at": "2026-08-20T10:00:00Z", "stations": [ { "station": "CNN", "count": 877267 }, { "station": "FOXNEWS", "count": 700230 }, { "station": "MSNBC", "count": 1135954 } ] } } ```
/gdelt/tv-showchartReturn the top shows by result percentage for a query
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "cap:\"trump\" station:CNN", "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=showchart&query=cap%3A%22trump%22+station%3ACNN", "fetched_at": "2026-08-20T10:00:00Z", "shows": [ { "show": "Anderson Cooper 360", "count": 7.8383 }, { "show": "Erin Burnett OutFront", "count": 5.4222 }, { "show": "CNN Newsroom Live", "count": 5.2105 } ] } } ```
/gdelt/tv-wordcloudReturn a frequency-ranked word/label cloud for one match
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "query": "cap:\"trump\" station:CNN", "channel": "caption", "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=wordcloudcap&query=cap%3A%22trump%22+station%3ACNN", "fetched_at": "2026-08-20T10:00:00Z", "words": [ { "label": "Trump", "count": 100.0 }, { "label": "Donald", "count": 22.1239 }, { "label": "President", "count": 2.2124 } ] } } ```
/gdelt/tv-stationdetailsReturn GDELT's own current list of Television 2.0 AI
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=stationdetails", "fetched_at": "2026-08-20T10:00:00Z", "stations": [ { "id": "KGO", "label": "ABC", "label_long": "ABC (KGO) (7/15/2010 - Now)" }, { "id": "CNN", "label": "CNN", "label_long": "CNN (1/1/2020 - Now)" } ] } } ```
/gdelt/tv-concept-entitiesReturn GDELT's own catalog of Google Knowledge Graph concept
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=capnlpentitydetails&maxrecords=100", "fetched_at": "2026-08-20T10:00:00Z", "entities": [ { "mid": "/m/09c7w0", "label": "U.S." }, { "mid": "/m/0cqt90", "label": "DONALD TRUMP" }, { "mid": "/m/016bvz", "label": "NBC NEWS" } ] } } ```
/gdelt/tv-visual-entitiesReturn GDELT's own catalog of computer-vision object/activity
Response notes
- `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. Example response: ```json { "code": 200, "msg": "OK", "data": { "source_url": "https://api.gdeltproject.org/api/v2/tvai/tvai?format=json&mode=visualentitydetails&maxrecords=100", "fetched_at": "2026-08-20T10:00:00Z", "entities": [ { "label": "person" }, { "label": "snapshot" }, { "label": "photograph" } ] } } ```
Related APIs
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.
How to scrape 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.
FAQ
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.