canonical: https://jentic.com/apis/api.gdeltproject.org/gdelt # Gdeltproject GDELT DOC 2.0 API 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. ## For AI 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. ## Scope 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. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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'. Example prompt: 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. Example prompt: 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 | Method | Path | Description | | --- | --- | --- | | GET | `/doc/doc` | Search global news articles with mode-controlled output (ArtList, TimelineVol, TimelineTone, ImageCollage, etc.) | ## Key resources - **Doc** — Full-text search across global news with multiple output modes (article list, time-line, tone, images, word cloud) ## Why Jentic - **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 handling:** 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. - **Discovery method:** 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 - **NewsAPI** — Aggregated English-language news search across major outlets with simpler query model - **Data.gov** — US federal data catalogue useful for cross-referencing GDELT coverage of policy events with the underlying datasets - **NASA APOD** — Open scientific dataset useful for projects pairing GDELT geopolitical coverage with science and exploration context ## FAQ ### 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.