Source: [canonical HTML](https://gdeltcloud.com/gdelt-api)
Developer guide · Updated 13 November 2026
# GDELT Project API guide: DOC 2.0, Events, GKG and GEO
The GDELT Project's APIs need no key. The DOC 2.0 API searches the last three months of online news, Events and the Global Knowledge Graph arrive as files every 15 minutes, and BigQuery holds both. Here is what each returns, its limits and errors, and where GDELT Cloud's REST API and MCP server fit.
## Which GDELT Project API do you need?
| API or feed | Returns | Time window | Access |
| --- | --- | --- | --- |
| DOC 2.0 API | Article lists, volume and tone timelines, and image collages for a full-text query over online news in 65 machine-translated languages[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) | Article lists: the latest 3 months. Timelines: from 1 January 2017[\[1\]](https://gdeltcloud.com/gdelt-api#source-1)[\[2\]](https://gdeltcloud.com/gdelt-api#source-2) | HTTP GET, no key; rate-limited[\[3\]](https://gdeltcloud.com/gdelt-api#source-3)[\[4\]](https://gdeltcloud.com/gdelt-api#source-4) |
| GEO 2.0 API | Maps of the locations mentioned in matching coverage, as GeoJSON or HTML[\[5\]](https://gdeltcloud.com/gdelt-api#source-5) | 24 hours by default, up to 7 days[\[5\]](https://gdeltcloud.com/gdelt-api#source-5)[\[6\]](https://gdeltcloud.com/gdelt-api#source-6) | Answered HTTP 404 to our request on 13 November 2026[\[7\]](https://gdeltcloud.com/gdelt-api#source-7) |
| Context 2.0 API | Articles with the sentence that matched the query[\[8\]](https://gdeltcloud.com/gdelt-api#source-8) | A rolling 72 hours[\[9\]](https://gdeltcloud.com/gdelt-api#source-9) | HTTP GET, no key; rate-limited[\[3\]](https://gdeltcloud.com/gdelt-api#source-3)[\[4\]](https://gdeltcloud.com/gdelt-api#source-4) |
| TV 2.0 API | Matches in the closed captions of the Internet Archive's Television News Archive[\[10\]](https://gdeltcloud.com/gdelt-api#source-10) | Station archives from July 2009[\[10\]](https://gdeltcloud.com/gdelt-api#source-10) | HTTP GET, no key[\[3\]](https://gdeltcloud.com/gdelt-api#source-3) |
| Events 2.0 | CAMEO-coded events with actors, location and a Goldstein score, plus a Mentions table[\[11\]](https://gdeltcloud.com/gdelt-api#source-11) | From February 2015; version 1.0 events from 1979[\[12\]](https://gdeltcloud.com/gdelt-api#source-12)[\[13\]](https://gdeltcloud.com/gdelt-api#source-13) | Files every 15 minutes, or BigQuery; no query API[\[12\]](https://gdeltcloud.com/gdelt-api#source-12)[\[3\]](https://gdeltcloud.com/gdelt-api#source-3) |
| GKG 2.0 | Per-article persons, organizations, locations, themes, tone and emotions[\[14\]](https://gdeltcloud.com/gdelt-api#source-14) | From February 2015[\[12\]](https://gdeltcloud.com/gdelt-api#source-12) | Files every 15 minutes, or BigQuery[\[12\]](https://gdeltcloud.com/gdelt-api#source-12)[\[3\]](https://gdeltcloud.com/gdelt-api#source-3) |
## The DOC 2.0 API
The DOC 2.0 API answers a full-text query over monitored online news with one GET request. Its documentation is the GDELT Project's announcement post[\[1\]](https://gdeltcloud.com/gdelt-api#source-1). This is the request we sent while writing this guide:
Request
```
https://api.gdeltproject.org/api/v2/doc/doc?query=%22port%20strike%22&mode=ArtList&format=json&maxrecords=3×pan=3d&sort=DateDesc
```
| Parameter | What it does |
| --- | --- |
| `query` | The search. Phrases go in quotes, OR terms inside parentheses, and a minus sign excludes a word. Operators such as `sourcecountry:`, `sourcelang:`, `domain:`, `theme:`, `near20:` and `tone<` narrow it[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
| `mode` | What to return: `ArtList` for articles, `TimelineVol` and `TimelineVolRaw` for coverage volume, `TimelineTone`, `TimelineLang`, `TimelineSourceCountry`, `ToneChart`, and image modes[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
| `format` | `HTML` by default, or `CSV`, `RSS`, `RSSArchive`, `JSON`, `JSONP` and `JSONFeed`. The RSS formats and JSONFeed work with ArtList only[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
| `maxrecords` | Articles per ArtList call: 75 by default, at most 250[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
| `timespan` | A relative window such as `24h`, `7d`, `2w` or `3m`; at least 15 minutes[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
| `startdatetime, enddatetime` | An absolute window, written `YYYYMMDDHHMMSS`[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
| `sort` | Relevance by default; `DateDesc`, `DateAsc`, `ToneDesc`, `ToneAsc` or `HybridRel`[\[1\]](https://gdeltcloud.com/gdelt-api#source-1) |
ArtList returns articles from the latest 3 months even when the window is wider; the timeline modes reach back to 1 January 2017[\[2\]](https://gdeltcloud.com/gdelt-api#source-2). Coverage in 65 languages is searched through machine translation, and `sourcelang:` filters by an article's original language[\[1\]](https://gdeltcloud.com/gdelt-api#source-1).
## Rate limits and errors
The GDELT Project rate-limits the DOC and Context APIs without publishing a number, and points high-volume users to downloadable datasets such as Web NGrams 3.0[\[4\]](https://gdeltcloud.com/gdelt-api#source-4).
On 13 November 2026, the 4 DOC requests we sent from one machine between 18:44 UTC and 18:49 UTC, at least 30 seconds apart, were all answered HTTP 429, with no Content-Type and no Retry-After header[\[15\]](https://gdeltcloud.com/gdelt-api#source-15). The body, with a personal address removed:
HTTP 429 Too Many Requests
```
Please limit requests to one every 5 seconds or contact [address removed] for larger queries. All high-traffic users should switch to our ngrams dataset: https://blog.gdeltproject.org/using-the-new-web-ngrams-dataset-to-find-relevant-coverage/. For trend analysis, please see our daily newsletter briefings: https://blog.gdeltproject.org/announcing-our-new-daily-todays-trends-on-capitol-hill-todays-media-trends-newsletter-briefings/.
```
Errors are not always HTTP errors. The gdeltdoc client notes that an invalid request can come back as HTTP 200 with a text or HTML message in place of JSON[\[16\]](https://gdeltcloud.com/gdelt-api#source-16). So a client should:
- check the status code and the Content-Type before parsing JSON;
- back off on 429 with its own delay, since no Retry-After is sent;
- cache results, and move large or repeated pulls to the files or BigQuery.
## Keys, accounts and BigQuery
The GDELT Project's APIs and files need no key and no account. Its terms allow any use, including commercial, provided the use cites the GDELT Project and links to its website[\[17\]](https://gdeltcloud.com/gdelt-api#source-17)[\[3\]](https://gdeltcloud.com/gdelt-api#source-3).
BigQuery is the exception. Queries run in your own Google Cloud project: Google stores the public data and you pay for the queries[\[18\]](https://gdeltcloud.com/gdelt-api#source-18). The first 1 TiB of queries each month is free, and on-demand queries then cost $6.25 per TiB scanned at Google's US list price[\[19\]](https://gdeltcloud.com/gdelt-api#source-19). The BigQuery sandbox needs no card[\[20\]](https://gdeltcloud.com/gdelt-api#source-20). Filtering the partitioned tables by date scans less[\[21\]](https://gdeltcloud.com/gdelt-api#source-21).
## Events and GKG: files and BigQuery
Events 2.0 and the GKG 2.0 are feeds, not query APIs. Every 15 minutes the GDELT Project publishes a zipped events export, a mentions file and a GKG file; `lastupdate.txt` names the newest three and `masterfilelist.txt` the full list[\[12\]](https://gdeltcloud.com/gdelt-api#source-12). The files are tab-delimited despite the `.CSV` in their names[\[11\]](https://gdeltcloud.com/gdelt-api#source-11).
lastupdate.txt, read at 18:45 UTC on 13 November 2026
```
83421 d04c13fb6ebfe611e33176392ba2429a http://data.gdeltproject.org/gdeltv2/20261113184500.export.CSV.zip
128341 11093ee034465677232c96e06bb8c25c http://data.gdeltproject.org/gdeltv2/20261113184500.mentions.CSV.zip
5970680 f2b6984d62e22c5cfa2cbdd3e1f5899b http://data.gdeltproject.org/gdeltv2/20261113184500.gkg.csv.zip
```
Each line gives the file size in bytes, a checksum and the file's URL[\[22\]](https://gdeltcloud.com/gdelt-api#source-22). Events use dyadic CAMEO coding, in which one actor acts on another, with an event code and a Goldstein scale score[\[11\]](https://gdeltcloud.com/gdelt-api#source-11). The GKG records, for each article, the persons, organizations, locations, counts, themes, tone and emotions it mentions[\[14\]](https://gdeltcloud.com/gdelt-api#source-14).
In BigQuery the same data is in `gdelt-bq.gdeltv2.events`, `gdelt-bq.gdeltv2.eventmentions` and `gdelt-bq.gdeltv2.gkg`, with partitioned copies such as `gkg_partitioned`[\[12\]](https://gdeltcloud.com/gdelt-api#source-12)[\[21\]](https://gdeltcloud.com/gdelt-api#source-21). Version 1.0 events are published as files back to 1979[\[13\]](https://gdeltcloud.com/gdelt-api#source-13).
## Where GDELT Cloud fits
GDELT Cloud is a separate service built on the GDELT Project article stream. It reads the stream's article URLs and metadata every hour, then codes its own Events, clusters the reporting into Stories and resolves people, organizations and places to Entities[\[23\]](https://gdeltcloud.com/gdelt-api#source-23). It does not re-serve the GDELT Project's Events or GKG rows.
| With the GDELT Project | With GDELT Cloud |
| --- | --- |
| DOC article lists for a topic | `GET /api/v2/stories?search=…`: Stories that group the reporting, each with its source articles |
| DOC volume timelines | `GET /api/v2/events/summary` or `/api/v2/stories/summary`, grouped by date |
| Events 2.0 rows | `GET /api/v2/events`: GDELT Cloud's own coded Events |
| GKG persons and organizations | `GET /api/v2/entities`: resolved Entities |
| GEO maps | `GET /api/v2/events?near=lat,lon&radius_km=…`: coordinates on every located Event |
### A real request
A topic search in GDELT Cloud is a Story search. This response is real, captured on 13 November 2026 with a test key[\[24\]](https://gdeltcloud.com/gdelt-api#source-24):
Request
```
curl "https://gdeltcloud.com/api/v2/stories?search=election&date_start=2026-11-11&date_end=2026-11-11&limit=2" \
-H "Authorization: Bearer $GDELT_API_KEY"
```
Response, first Story (excerpt)2 Stories · 1 Query Unit
```
{
"id": "1c619f83e512",
"url": "https://gdeltcloud.com/stories/voter-turnout-rises-in-minnesotas-midterm-election-1c619f83",
"title": "Voter turnout rises in Minnesota's midterm election",
"story_date": "2026-11-11",
"category": "Political",
"geo": {
"country": "United States",
"region": "North America",
"continent": "North America",
"admin1": null,
"location": null,
"latitude": null,
"longitude": null,
"geo_precision": null,
"geo_precision_label": null
},
"has_events": false,
"linked_events": [],
"top_articles": [
{
"url": "https://www.businessnorth.com/minnesota_public_radio/voter-turnout-up-in-minnesotas-midterm-election/article_cc430a19-6eee-4f94-9e3b-8aec7f7bbad9.html",
"title": "Voter turnout up in Minnesota's midterm election",
"domain": "businessnorth.com"
}
],
"language_breakdown": [
{
"language": "en",
"count": 1
}
]
}
```
Keys go in `Authorization: Bearer gdelt_sk_…`, belong to a workspace and are metered in Query Units. A free account includes a one-time 200-call starter credit[\[25\]](https://gdeltcloud.com/gdelt-api#source-25).
### Errors are JSON
A misspelled value is answered 400 with an error code, the nearest valid values and an example[\[26\]](https://gdeltcloud.com/gdelt-api#source-26). A real response to `/api/v2/events?category=Battle&days=1`, without the full list of accepted values it also carries:
HTTP 400
```
{
"success": false,
"code": "INVALID_CATEGORY",
"details": {
"param": "category",
"invalid_value": "Battle",
"nearest_values": [
"Battles",
"CRIME",
"HEALTH"
],
"example": "?category=Battles"
}
}
```
Agents reach the same data through the MCP server at `https://mcp.gdeltcloud.com/mcp`[\[27\]](https://gdeltcloud.com/gdelt-api#source-27).
## Which to use
| You need | Use |
| --- | --- |
| Keyless search of the last three months of news, or volume timelines since 2017 | The GDELT Project's DOC 2.0 API |
| Every raw event and knowledge-graph row since 2015 in your own pipeline | The GDELT Project's files or BigQuery |
| Coded Events, Stories and Entities through one authenticated API and an MCP server | GDELT Cloud |
## Next
[Get a GDELT Cloud API key ↗](https://docs.gdeltcloud.com/api-keys)[Global events database →](https://gdeltcloud.com/data/global-events-database)[Conflict data API →](https://gdeltcloud.com/data/conflict-data-api)[GDELT Project alternatives compared →](https://gdeltcloud.com/compare/gdelt-alternatives)
## Sources
1. [1] The GDELT Project, [GDELT DOC 2.0 API Debuts!](https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/)checked 13 November 2026
2. [2] The GDELT Project, [DOC 2.0 Updates: 1.5 Year Searching and Updated Mobile Interface](https://blog.gdeltproject.org/doc-2-0-updates-1-5-year-searching-and-updated-mobile-interface/)checked 13 November 2026
3. [3] The GDELT Project, [Data](https://www.gdeltproject.org/data.html)checked 13 November 2026
4. [4] The GDELT Project, [Ukraine, API Rate Limiting & Web NGrams 3.0](https://blog.gdeltproject.org/ukraine-api-rate-limiting-web-ngrams-3-0/)checked 13 November 2026
5. [5] The GDELT Project, [GDELT GEO 2.0 API Debuts!](https://blog.gdeltproject.org/gdelt-geo-2-0-api-debuts/)checked 13 November 2026
6. [6] The GDELT Project, [DOC & GEO 2.0 API Updates: Full Year Searching and More](https://blog.gdeltproject.org/doc-geo-2-0-api-updates-full-year-searching-and-more/)checked 13 November 2026
7. [7] GDELT Cloud, [GEO 2.0 API request sent 18:48 UTC](https://api.gdeltproject.org/api/v2/geo/geo)Our requestchecked 13 November 2026
8. [8] The GDELT Project, [Announcing the GDELT Context 2.0 API](https://blog.gdeltproject.org/announcing-the-gdelt-context-2-0-api/)checked 13 November 2026
9. [9] The GDELT Project, [Context 2.0 API to Support Three-Day Search Horizon](https://blog.gdeltproject.org/context-2-0-api-to-support-three-day-search-horizon/)checked 13 November 2026
10. [10] The GDELT Project, [GDELT 2.0 Television API Debuts!](https://blog.gdeltproject.org/gdelt-2-0-television-api-debuts/)checked 13 November 2026
11. [11] The GDELT Project, [GDELT Event Codebook V2.0 (PDF)](https://data.gdeltproject.org/documentation/GDELT-Event_Codebook-V2.0.pdf)checked 13 November 2026
12. [12] The GDELT Project, [GDELT 2.0: Our Global World in Realtime](https://blog.gdeltproject.org/gdelt-2-0-our-global-world-in-realtime/)checked 13 November 2026
13. [13] The GDELT Project, [GDELT 1.0 event files](http://data.gdeltproject.org/events/index.html)checked 13 November 2026
14. [14] The GDELT Project, [GDELT Global Knowledge Graph Codebook V2.1 (PDF)](https://data.gdeltproject.org/documentation/GDELT-Global_Knowledge_Graph_Codebook-V2.1.pdf)checked 13 November 2026
15. [15] GDELT Cloud, [DOC 2.0 API requests sent 18:44 to 18:50 UTC](https://api.gdeltproject.org/api/v2/doc/doc)Our requestchecked 13 November 2026
16. [16] GitHub, alex9smith, [gdeltdoc, a Python client for the DOC 2.0 API](https://github.com/alex9smith/gdelt-doc-api)Third partychecked 13 November 2026
17. [17] The GDELT Project, [Terms of use](https://www.gdeltproject.org/about.html#termsofuse)checked 13 November 2026
18. [18] Google Cloud, [BigQuery public datasets](https://cloud.google.com/bigquery/public-data)checked 13 November 2026
19. [19] Google Cloud, [BigQuery pricing](https://cloud.google.com/bigquery/pricing)checked 13 November 2026
20. [20] Google Cloud, [Use the BigQuery sandbox](https://cloud.google.com/bigquery/docs/sandbox)checked 13 November 2026
21. [21] The GDELT Project, [Announcing Partitioned GDELT BigQuery Tables](https://blog.gdeltproject.org/announcing-partitioned-gdelt-bigquery-tables/)checked 13 November 2026
22. [22] GDELT Cloud, [lastupdate.txt read at 18:45 UTC](https://data.gdeltproject.org/gdeltv2/lastupdate.txt)Our requestchecked 13 November 2026
23. [23] GDELT Cloud, [Methodology](https://gdeltcloud.com/methodology)checked 13 November 2026
24. [24] GDELT Cloud, [API responses captured for these pages](https://docs.gdeltcloud.com/api-reference)Our requestchecked 13 November 2026
25. [25] GDELT Cloud docs, [API keys](https://docs.gdeltcloud.com/api-keys)checked 13 November 2026
26. [26] GDELT Cloud docs, [Error reference](https://docs.gdeltcloud.com/reference/errors)checked 13 November 2026
27. [27] GDELT Cloud docs, [MCP server](https://docs.gdeltcloud.com/mcp/overview)checked 13 November 2026