Gdeltproject GDELT DOC 2.0 API
★ Only Publicly Available OpenAPI DocumentData EnrichmentData Transformationnone1 EndpointsREST
For Agents
Search global news coverage across 65 languages from the last three months and retrieve articles, time-lines, tone charts, or image collages from the GDELT 2.0 dataset.
Use for: Search global news for articles mentioning a company in the last week, I want to plot a daily volume of coverage for a topic, Get a tone chart showing sentiment about a country's elections, Find news articles from a specific source language about a topic
Not supported: Does not handle real-time push of new articles, deep historical archives beyond 3 months, or full article body retrieval - use for global news search and aggregate analysis only.
Jentic publishes the only available OpenAPI specification for GDELT DOC 2.0 API, keeping it validated and agent-ready. The GDELT DOC 2.0 API exposes full-text search across the entire GDELT 2.0 universe of global news coverage, which GDELT monitors from across the world and machine translates into English, spanning a rolling three-month window across 65 languages. The single /doc/doc endpoint is accessed as a simple URL and supports query operators for source country, source language, GKG theme and publisher domain, plus multiple output modes (article list, image collage, time-line, tone chart, word cloud), making it a foundational primitive for media monitoring, geopolitical research, and event-driven analytics.
Install Jentic One Beta
Connect the GDELT DOC 2.0 API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the GDELT DOC 2.0 API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapi.gdeltproject.org%2Fgdelt" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fapi.gdeltproject.org%2Fgdelt" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with GDELT DOC 2.0 API.
Search global news articles by keyword across 65 languages and 3 months of coverage
Filter results by source country, source language, GKG theme, or publisher domain
Return matching articles as a list with title, URL, publisher domain, language, and source country
Generate a time-line of article volume for a query over the searched window
Produce a tone chart showing sentiment of coverage on a topic over time
Pull a collage of images extracted from articles matching a query
Use Cases
Patterns agents use GDELT DOC 2.0 API for, with concrete tasks.
★ Media Monitoring at Global Scale
Run a media monitoring brief that covers global news in 65 languages for a brand, executive, or topic - far wider than English-only press monitoring tools. The /doc/doc endpoint supports keyword and theme queries with country and language filters, returning matching articles with title, URL, publisher domain, language, and source country for downstream analysis or alerting.
GET /doc/doc?query="acme corporation"&mode=ArtList&maxrecords=250&format=json to fetch the latest 250 matching articles across all languages
Geopolitical and Market Research
Track global coverage volume and tone around events relevant to investing or policy: elections, sanctions, conflict, supply chain disruption. The TimelineVol mode returns daily counts and the TimelineTone mode returns sentiment, enabling charts that contextualise market or policy responses against actual news flow.
GET /doc/doc?query="central bank rate hike"&mode=TimelineTone×pan=1month to plot tone of coverage over the last month
Event Detection for Analytics
Detect emerging stories around competitors, regulators, or markets by polling GDELT for sudden spikes in coverage volume on tracked queries. Pair the /doc/doc TimelineVol mode with a baseline computed from prior weeks to flag anomalies. Pace the polling: called too quickly, the API answers HTTP 429 with the message 'Please limit requests to one every 5 seconds'.
GET /doc/doc?query="competitor product recall"&mode=TimelineVol×pan=1week and compare daily volumes against the prior 4-week baseline to detect a spike
AI Research Agent via Jentic
An AI research or briefing agent can call GDELT through Jentic to answer "what's been said about X globally in the last week?" The single /doc/doc endpoint with structured query and mode parameters fits cleanly into agent tool schemas, and Jentic surfaces it as a discoverable operation with its input schema attached.
Search Jentic for 'search global news', load the GET /doc/doc schema, and execute with query and mode=ArtList to return ranked article hits
Key Endpoints
1 endpoints — jentic publishes the only available openapi specification for gdelt doc 2.
METHOD
PATH
DESCRIPTION
GET
/doc/doc
Search global news articles with mode-controlled output (ArtList, TimelineVol, TimelineTone, ImageCollage, etc.)
GET
/doc/doc
Search global news articles with mode-controlled output (ArtList, TimelineVol, TimelineTone, ImageCollage, etc.)
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the GDELT DOC 2.0 API by hand means building your own query construction and response parsing against its single doc search endpoint, including its mode and format switches and the operator syntax that has to live inside the query value. Through Jentic you install once, import the GDELT DOC 2.0 API from the API Directory, and your agent calls it without hand-wiring the request format.
Permission scoping
GDELT DOC 2.0 exposes a single read-only search endpoint whose query travels as request parameters, so the agent is limited to that one search operation and nothing more. Every operation you grant is your explicit choice.
Credential isolation
GDELT's DOC 2.0 documentation describes no credential for this API, so there is nothing here for Jentic to inject. Calls still run through your own self-hosted Jentic One instance, which is where credentials are held for the APIs you connect alongside it, and request handling stays out of the agent's prompt, logs, and context.
Intent-based discovery
Agents search Jentic by intent such as 'search global news coverage of a topic' or 'get an aggregate timeline of articles', and Jentic returns the matching GDELT operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using GDELT DOC 2.0 API through Jentic.
Why is there no official OpenAPI spec for GDELT DOC 2.0 API?
GDELT publishes narrative documentation rather than an OpenAPI spec. Jentic generates and maintains this spec so that AI agents and developers can call GDELT DOC 2.0 API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the GDELT DOC 2.0 API use?
GDELT's own DOC 2.0 documentation describes no credential for this API. It states that the API is accessed via a simple URL with the documented parameters, and every request example it publishes carries only parameters such as query, mode and timespan with nothing key-shaped attached; the spec declares no security scheme either. What the endpoint does enforce is a request rate, answering HTTP 429 with the message 'Please limit requests to one every 5 seconds' when it is called too quickly.
How far back does GDELT DOC 2.0 search go?
The DOC 2.0 endpoint covers a rolling three-month window of global news. For longer historical research, GDELT also publishes raw event and GKG bulk files separately, but those are outside the scope of the /doc/doc endpoint exposed here.
What output modes does the /doc/doc endpoint support?
The mode parameter controls the output: ArtList returns matching articles, TimelineVol returns the volume of matching coverage over time, TimelineTone returns its average tone, ImageCollage returns matching images processed by the GDELT Visual Global Knowledge Graph, and WordCloudImageTags returns a histogram of the topics tagged in that imagery. Mode is selected on the same single endpoint.
How do I run a GDELT search through Jentic?
Install self-hosted Jentic One from its GitHub repo, then search 'search global news'. Jentic returns the GET /doc/doc operation. Execute it with the query, mode (e.g. ArtList) and timespan parameters, and Jentic returns the structured response.
Is there a GDELT DOC 2.0 API MCP server?
You do not need an MCP server to give your agent GDELT DOC 2.0. Jentic connects the API directly from the Jentic API Directory: import it into your self-hosted Jentic One instance and your agent calls the GET /doc/doc operation on demand, without another server's tool definitions sitting in its context.
What query operators does the API support?
Queries support exact phrase quoting, OR statements, source country (sourcecountry), source language (sourcelang), GDELT GKG themes (theme), publisher domain (domain and domainis) and word proximity (near). GDELT requires these operators to be used inside the value of the query parameter rather than as URL parameters of their own; the timespan parameter sets the window inside the rolling 3 months.
Can I limit what my agent is allowed to do with the GDELT DOC 2.0 API?
Yes. Because Jentic One is self-hosted, your own rules decide which operations your agent can call, and GDELT DOC 2.0 exposes only a single read-only search operation, the GET /doc/doc endpoint. When you grant that operation to your agent, it can run news searches and aggregate modes like ArtList, TimelineVol, and TimelineTone through the query parameters, and nothing beyond that one search. Scoping here comes down to whether you allow that one operation at all.
GET STARTED