GDELT Project API guide: DOC 2.0, Events, GKG and GEO

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]. This is the request we sent while writing this guide:

https://api.gdeltproject.org/api/v2/doc/doc?query=%22port%20strike%22&mode=ArtList&format=json&maxrecords=3&timespan=3d&sort=DateDesc

ArtList returns articles from the latest 3 months even when the window is wider; the timeline modes reach back to 1 January 2017^[2]. Coverage in 65 languages is searched through machine translation, and sourcelang: filters by an article's original language^[1].

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

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]. The body, with a personal address removed:

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

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][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]. 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]. The BigQuery sandbox needs no card^[20]. Filtering the partitioned tables by date scans less^[21].

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]. The files are tab-delimited despite the .CSV in their names^[11].

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]. Events use dyadic CAMEO coding, in which one actor acts on another, with an event code and a Goldstein scale score^[11]. The GKG records, for each article, the persons, organizations, locations, counts, themes, tone and emotions it mentions^[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][21]. Version 1.0 events are published as files back to 1979^[13].

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]. It does not re-serve the GDELT Project's Events or GKG rows.

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]:

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"

{
  "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].

Errors are JSON

A misspelled value is answered 400 with an error code, the nearest valid values and an example^[26]. A real response to /api/v2/events?category=Battle&days=1, without the full list of accepted values it also carries:

{
  "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].

1. [1] The GDELT Project, 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 Interfacechecked 13 November 2026
3. [3] The GDELT Project, Datachecked 13 November 2026
4. [4] The GDELT Project, Ukraine, API Rate Limiting & Web NGrams 3.0checked 13 November 2026
5. [5] The GDELT Project, 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 Morechecked 13 November 2026
7. [7] GDELT Cloud, GEO 2.0 API request sent 18:48 UTCOur requestchecked 13 November 2026
8. [8] The GDELT Project, Announcing the GDELT Context 2.0 APIchecked 13 November 2026
9. [9] The GDELT Project, Context 2.0 API to Support Three-Day Search Horizonchecked 13 November 2026
10. [10] The GDELT Project, GDELT 2.0 Television API Debuts!checked 13 November 2026
11. [11] The GDELT Project, GDELT Event Codebook V2.0 (PDF)checked 13 November 2026
12. [12] The GDELT Project, GDELT 2.0: Our Global World in Realtimechecked 13 November 2026
13. [13] The GDELT Project, GDELT 1.0 event fileschecked 13 November 2026
14. [14] The GDELT Project, 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 UTCOur requestchecked 13 November 2026
16. [16] GitHub, alex9smith, gdeltdoc, a Python client for the DOC 2.0 APIThird partychecked 13 November 2026
17. [17] The GDELT Project, Terms of usechecked 13 November 2026
18. [18] Google Cloud, BigQuery public datasetschecked 13 November 2026
19. [19] Google Cloud, BigQuery pricingchecked 13 November 2026
20. [20] Google Cloud, Use the BigQuery sandboxchecked 13 November 2026
21. [21] The GDELT Project, Announcing Partitioned GDELT BigQuery Tableschecked 13 November 2026
22. [22] GDELT Cloud, lastupdate.txt read at 18:45 UTCOur requestchecked 13 November 2026
23. [23] GDELT Cloud, Methodologychecked 13 November 2026
24. [24] GDELT Cloud, API responses captured for these pagesOur requestchecked 13 November 2026
25. [25] GDELT Cloud docs, API keyschecked 13 November 2026
26. [26] GDELT Cloud docs, Error referencechecked 13 November 2026
27. [27] GDELT Cloud docs, MCP serverchecked 13 November 2026