> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Concepts & Response Objects
> Cross-cutting v2 reference — authentication, geography and bounding boxes, result coverage, the Event/Story/summary response schemas, entity resolution, and the significance ranking model.
This page covers the conventions shared across every v2 endpoint. For the controlled vocabularies you
pass as parameters, see [Taxonomy & Codes](/api-reference/taxonomy); for copy-paste recipes, see the
[Cookbook](/api-reference/cookbook).
## Authentication
Every `/api/v2/*` request authenticates with a Bearer API key:
```bash theme={null}
Authorization: Bearer gdelt_sk_...
```
Manage keys in the GDELT Cloud dashboard under **Settings → API Keys**. See
[Authentication](/authentication) for session vs. key auth and plan access.
## Result coverage
Event, Story, and Entity **list** endpoints default to the exact past 24 hours while preserving broad
discovery coverage, so you can find useful records before narrowing with structured filters. Confidence
tuning is handled internally. **Detail** endpoints remain exhaustive by ID:
`GET /api/v2/events/{event_id}` and `GET /api/v2/stories/{story_id}` resolve known records directly.
Explicit `date_start`/`date_end` windows filter by event/story date and may not exceed **30 days**.
## Geography
Use plain-English country names in calls; ISO-3 and legacy FIPS aliases are accepted, but responses
normalize country output to the plain-English name.
```bash theme={null}
country=France
country=United States
country=South Korea
```
`region` and `continent` expand to ISO-3 country lists on the backend. Event queries match those
countries against Event location **plus** actor-origin countries; Story queries use the same expansion
through linked-Event location only. `admin1` is optional and filters only the event/story location.
The `geo` object is the primary event/story location. For Events, when a broad geo filter matches
actor-origin geography instead, `geo_context.actor_origin_countries` shows why the record matched. For
Stories, `geo_context.actor_origin_countries` is returned for context but does not drive the geo filter.
See [Taxonomy & Codes → Geography](/api-reference/taxonomy#geography) for the full continent and region
enums.
### Bounding box
Use `bbox` for sub-country filters such as straits, ports, basins, border zones, or any custom viewport.
It is a comma-separated string in **latitude-first** order:
```bash theme={null}
bbox=lat_min,lon_min,lat_max,lon_max
```
`lat` must be in `[-90, 90]` and `lon` in `[-180, 180]`. The filter applies to the Event's primary
`geo.latitude`/`geo.longitude` (and to linked-Event locations for Stories). Records without geocoded
coordinates are excluded from `bbox` queries.
`bbox` is supported on `/api/v2/events`, `/api/v2/events/summary`, `/api/v2/stories`, and
`/api/v2/stories/summary`. `/api/v2/energy/assets` accepts the same lat-first `bbox` plus a separate
`near=lat,lon,radius_km` proximity filter.
The preview **Maritime** endpoints use a **longitude-first** `bbox` (`minLon,minLat,maxLon,maxLat`) —
the opposite axis order from Events/Stories/Energy. Watch the order when crossing surfaces.
## Response objects
List endpoints return a success envelope with `data` and `pagination`; detail endpoints return a single
`data` object; summary endpoints return `group_by` and grouped `data` buckets.
```json theme={null}
{
"success": true,
"data": [],
"pagination": { "limit": 25, "cursor": null, "next_cursor": "25" }
}
```
### Event card
Returned by `GET /api/v2/events` and `GET /api/v2/events/{event_id}`.
```json theme={null}
{
"id": "conflict_20260417_example",
"url": "https://gdeltcloud.com/story/example-story",
"primary_story_url": "https://gdeltcloud.com/story/example-story",
"family": "conflict",
"title": "Example event title",
"summary": "Short generated event summary.",
"event_date": "2026-04-17",
"category": "Protests",
"subcategory": "Peaceful protest",
"domain": "CONFLICT",
"event_code": "ACLED-123",
"geo": {
"country": "France", "region": "Europe", "continent": "Europe",
"admin1": "Ile-de-France", "location": "Paris",
"latitude": 48.8566, "longitude": 2.3522
},
"geo_context": { "location_country": "France", "actor_origin_countries": ["France"] },
"actors": [ { "name": "Protesters", "country": "France", "role": "actor1" } ],
"metrics": {
"significance": 0.72, "goldstein_scale": -2, "magnitude": null,
"systemic_importance": null, "propagation_potential": null,
"market_sensitivity": null, "confidence": 0.91, "article_count": 4
},
"has_fatalities": false, "fatalities": 0,
"civilian_targeting": false, "civilian_targeting_label": null,
"story_refs": [ { "id": "story_20260417_example", "url": "https://gdeltcloud.com/story/example-story", "title": "Example story", "story_date": "2026-04-17", "article_count": 4 } ],
"entity_refs": [ { "id": "Paris", "name": "Paris", "type": "LOCATION", "wikipedia_url": "https://en.wikipedia.org/wiki/Paris" } ],
"top_articles": [ { "url": "https://example.com/article", "title": "Example article", "rank": 1 } ]
}
```
| Field | Description |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Stable v2 Event identifier. |
| `url`, `primary_story_url` | Public GDELT Cloud Story URL for citation when the Event has a linked Story. |
| `family` | `conflict` or `cameoplus`. |
| `title`, `summary` | Generated Event headline and concise summary. |
| `event_date` | Event date in `YYYY-MM-DD`. |
| `category`, `subcategory` | Taxonomy fields. Conflict Events use event types (`Battles`, `Protests`, …) as `category` and sub-event types (`Armed clash`, `Peaceful protest`, …) as `subcategory`; CAMEO+ Events use domains as `category` and stable codes (`TE01`, `IN03`, …) as `subcategory`. Responses display canonical labels such as `TE01 · AI Capability Event`. |
| `domain` | CAMEO+ domain, or `CONFLICT` for Conflict Events. |
| `event_code` | Source event id, CAMEO+ event code, or null. |
| `geo` | Primary Event location. |
| `geo_context` | Explains broad-geography matches, especially actor-origin matches. |
| `actors` | Event actors with `name`, normalized `country`, and `role`. |
| `metrics` | Event significance and its generated metric inputs. |
| `has_fatalities`, `fatalities` | Fatality flag and count. |
| `civilian_targeting`, `civilian_targeting_label` | Conflict-only ACLED civilian-targeting flag and label. |
| `story_refs` | Linked Story references with public URLs. |
| `entity_refs` | Linked Entities with names, types, and Wikipedia URLs when available. |
| `top_articles` | Top 3 inline source articles. Use the Story articles endpoint for full lists. |
### Story card
Returned by `GET /api/v2/stories` and `GET /api/v2/stories/{story_id}`.
```json theme={null}
{
"id": "story_20260417_example",
"url": "https://gdeltcloud.com/story/example-story",
"title": "Example story title",
"story_date": "2026-04-17",
"category": "infrastructure",
"subcategory": null,
"geo": {
"country": "Japan", "region": "East Asia", "continent": "Asia",
"admin1": "Tokyo", "location": "Tokyo", "latitude": 35.6762, "longitude": 139.6503
},
"geo_context": { "location_country": "Japan", "actor_origin_countries": ["Japan", "United States"] },
"metrics": { "significance": 0.82, "article_count": 12, "linked_event_count": 2, "max_linked_event_significance": 0.76 },
"has_events": true, "has_fatalities": false, "fatalities": 0,
"linked_events": [ { "id": "cameoplus_20260417_example", "title": "Example linked Event" } ],
"entity_refs": [ { "id": "Tokyo", "name": "Tokyo", "type": "LOCATION", "wikipedia_url": "https://en.wikipedia.org/wiki/Tokyo" } ],
"top_articles": [ { "url": "https://example.com/article", "title": "Example article", "domain": "example.com", "rank": 1 } ]
}
```
| Field | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| `id` | Stable v2 Story cluster identifier. |
| `url` | Public GDELT Cloud Story URL for citation. |
| `title`, `story_date` | Cluster headline and cluster date. |
| `category`, `subcategory` | Story category and linked-Event subcategory context when available. |
| `geo` | Primary geography inferred through linked Events. |
| `geo_context` | Location country plus actor-origin countries from linked Events. |
| `metrics` | Story significance, article volume, linked Event count, and max linked Event significance. |
| `has_events`, `linked_events` | Whether structured Events link to the Story, plus up to 10 linked Event refs. |
| `has_fatalities`, `fatalities` | Whether linked Events include fatalities, plus total linked fatalities. |
| `entity_refs` | Linked Entities with names, types, and Wikipedia URLs when available. |
| `top_articles` | Top 3 inline source articles for evidence preview. |
### Summary buckets
The **Event summary bucket** and **Story summary bucket** are returned by `GET /api/v2/events/summary`
and `GET /api/v2/stories/summary`. Buckets carry simple counts
plus nested aggregate statistics (`metrics` / `metric_stats`) for the inputs behind significance:
Goldstein scale/severity, CAMEO+ magnitude/systemic/propagation/market, confidence, article evidence, and
fatality counts/rates.
```json theme={null}
{
"success": true,
"group_by": "country",
"data": [
{
"key": "France",
"group_by": "country",
"event_count": 12,
"conflict_event_count": 4,
"cameoplus_event_count": 8,
"fatality_event_count": 2,
"fatalities": 6,
"article_count": 40,
"metrics": {
"significance": { "avg": 0.42, "max": 0.91, "min": 0.05 },
"goldstein_scale": { "avg": -3.8, "min": -8, "max": 2, "avg_severity": 4.2 },
"cameoplus": { "magnitude": { "avg": 6.1, "min": 1.2, "max": 9 } },
"article_count": { "total": 40, "avg": 3.333, "min": 1, "max": 12 },
"fatalities": { "events": 2, "rate": 0.1667, "total": 6 }
}
}
]
}
```
Story summary buckets use the same envelope and add `story_count`, `stories_with_events`,
`story_only_count`, linked-event counts, `avg_recency_score`, and nested `metrics.linked_events`.
`linked_event_count` is the number of Story-to-Event links, **not** a second Event total — use
`event_count` from Event summaries for distinct Events. Summary endpoints do not accept `search`.
### Articles, entities, admin1, and errors
Story article rows include source `domain`, `domain_avatar_url`, `image_url` (when available), `rank`,
and `role`. Entity cards are **canonical, deduplicated by Wikipedia URL** — multiple raw-name variants
("Trump" + "Donald Trump") collapse to one card; only People and Organizations with linked Wikipedia
pages are surfaced.
The `id` is a **universal canonical id** — an `e_…` id when the entity exists in the cross-source
reference spine (the same id `GET /api/v2/search` returns), otherwise a `wiki:…` id for the news-only
tail. Either form **round-trips on every entity-taking endpoint** (`/events?entity=`, `/entity-tone`,
`/share-of-voice`, `/gov/awards?entity=`, entity detail), so you can chain calls without remapping. The
Wikipedia URL is still returned as the `wikipedia_url` field.
```json theme={null}
{
"id": "wiki:3f2a1c9b7e5d4a6f8c02",
"url": "https://gdeltcloud.com/entities/person-example-person",
"name": "Example Person",
"type": "person",
"wikipedia_url": "https://en.wikipedia.org/wiki/Example_Person",
"metrics": { "article_count": 20, "story_count": 8, "event_count": 3 }
}
```
Raw per-article mention counts and entity salience scores are **not** part of the v2 entity contract.
GDELT Cloud surfaces aggregated Story, Article, and Event counts as the canonical activity signals.
`GET /api/v2/geo/admin1` returns a per-country list:
```json theme={null}
{ "success": true, "country": "France", "admin1": ["Bretagne", "Ile-de-France"], "source": "gdelt_cloud.events" }
```
Standard error responses carry `error`, a stable `code`, and `details` with `accepted_values`,
`nearest_values` when practical, and a corrected `example` so agents can retry without guessing:
```json theme={null}
{
"success": false,
"error": "Invalid continent. Use one of: Africa, Asia, Europe, North America, South America, Oceania",
"code": "INVALID_CONTINENT",
"details": {
"param": "continent",
"invalid_value": "Atlantis",
"accepted_values": ["Africa", "Asia", "Europe", "North America", "South America", "Oceania"],
"example": "?continent=Asia"
}
}
```
`subcategory` requires its parent `category`; for CAMEO+ categories, prefer stable event codes such as
`TE01` over label text. The legacy `event_family` and `domain` parameters are still accepted but
deprecated — `category` implies Conflict vs. CAMEO+.
## Entity aliases and resolution
GDELT Cloud resolves observed names — reordered names, initials, acronyms, common abbreviations — to a
single canonical entity through a proprietary resolution layer. Wikipedia-linked entities carry stable
canonical identifiers. Newly observed candidates enter the registry as `needs_review` and are promoted to
`active` once they meet confidence criteria, so workflows can distinguish "known entity with no score
yet" from "entity not found."
### Finding an entity when you don't know the exact name
```http theme={null}
GET /api/v2/entities/resolve?q=&scope=all
```
This is the fuzzy "find the entity" step — start here whenever you have a (possibly misspelled or
abbreviated) name rather than an id. `scope` chooses which registries to search:
* `scope=media` (default) — news-resolved entities only (people & organizations seen in coverage).
* `scope=reference` — the structured registry only (GEM energy owners, SEC/EDGAR filers, restricted-party list entries, China financiers).
* `scope=all` — everything: news + GEM + SEC/EDGAR + lists + China, deduplicated and ranked.
It returns ranked candidates (`entity_id`, display name, type, country, match reason, score). Resolve
once, then fan out across the event, energy, screening, and filings surfaces using the shared
`entity_id`. The matching index covers the full registry even for entities with no Wikipedia page yet.
## Ranking
The default sort is `sort=significance`. Event significance is a **family-scoped weighted blend**,
renormalized so every event family spans a true 0–1: each event's raw total is divided by the maximum its own
family can reach (Conflict `1.00`, CAMEO+ `POLITICAL` `0.90`, other CAMEO+ domains `0.65`).
| Applies to | Weights |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| **All events** | Goldstein severity `0.25` · article evidence `0.05` · confidence `0.05` |
| **Conflict only** | fatalities `0.55` (log-scaled by body count, saturating around 100 deaths) · civilian targeting `0.10` |
| **CAMEO+ only** | magnitude `0.20` · systemic importance `0.15` · propagation potential `0.10` · market sensitivity `0.10` |
When `magnitude` is unmeasured, **both** its term and its `0.20` weight are dropped for that event. The four
CAMEO+ inputs are rubric scores produced by fixed published formulas — ordinal ranking signals, not
measurements, probabilities, or predicted price moves (see
[Event metric filters](/api-reference/taxonomy#event-metric-filters)).
`goldstein_scale` is the signed −10…+10 scale; `goldstein_severity` is `abs(goldstein_scale)` and exists
as an aggregate/statistical helper for significance inputs. Story significance combines linked-Event
significance, capped article count, and recency. Use `sort=recent` when freshness matters more than
significance.
`goldstein_scale` is exposed as one canonical public Event metric — present for all Conflict Events and
CAMEO+ `POLITICAL` Events, null for non-political CAMEO+ domains where it is not meaningful.