GDELT Cloud Docs — Global Event Data API & MCP

This page is the single reference for the controlled vocabularies you pass to the v2 API: the event_family, category, subcategory, sort, group_by, confidence_profile, geography, and energy/maritime filters. Values are case-sensitive unless noted.

Most endpoints echo the values they actually applied back under applied_filters in the response. When in doubt, send a query and read applied_filters to confirm how your input resolved.

Event families

Pick one family per Events query with event_family. Stories carry both families and are filtered by story category instead.

`event_family`	What it covers
`conflict`	Generated Conflict Events — political violence, protests, riots, strategic developments, fatalities, and conflict geography (ACLED-style coding).
`cameoplus`	Generated CAMEO+ Events — the ten structural domains below (political, economic, corporate, technology, infrastructure, environment, health, demographic, information, crime).

Event categories & subcategories

category and subcategory accept either a Conflict event type or a CAMEO+ domain/code. They are an open vocabulary (the API also accepts close aliases and CAMEO+ code strings), so they render as free-text parameters in the playground — use the canonical values below.

Conflict event types

For event_family=conflict, category is one of six ACLED event types; subcategory is one of its sub-types.

Battles

Government regains territory · Non-state actor overtakes territory · Armed clash

Protests

Excessive force against protesters · Protest with intervention · Peaceful protest

Riots

Violent demonstration · Mob violence

Explosions/Remote violence

Chemical weapon · Air/drone strike · Suicide bomb · Shelling/artillery/missile attack · Remote explosive/landmine/IED · Grenade

Violence against civilians

Sexual violence · Attack · Abduction/forced disappearance

Strategic developments

Agreement · Arrests · Change to group/activity · Disrupted weapons use · Headquarters or base established · Looting/property destruction · Non-violent transfer of territory · Other

CAMEO+ domains

For event_family=cameoplus, category is one of ten domains. Each non-political domain uses a two-letter code prefix; POLITICAL uses standard CAMEO root codes.

Domain (`category`)	Prefix	Description
`POLITICAL`	CAMEO 01–17	Diplomatic, cooperative, verbal-conflict, and non-violent coercive political events.
`ECONOMIC`	`EC`	Macroeconomic, monetary, fiscal, trade, capital-flow, and market-stress events.
`CORPORATE`	`CO`	M&A, production, technology development, capital allocation, and corporate structure events.
`TECHNOLOGY`	`TE`	AI capability, military tech, cyber, space, and strategic technology-control events.
`INFRASTRUCTURE`	`IN`	Energy, transport, supply-chain, communications, and water infrastructure events.
`ENVIRONMENT`	`EN`	Geophysical hazards, meteorological events, climate events, and pollution.
`HEALTH`	`HE`	Epidemic outbreaks, pandemics, vaccine milestones, health policy, and system crises.
`DEMOGRAPHIC`	`DE`	Refugee flows, migration events, population crises, and labor events.
`INFORMATION`	`IF`	Disinformation, information control, major leaks, and narrative warfare.
`CRIME`	`CR`	Ordinary crime, criminal justice, policing, trafficking, organized crime, and custody events.

CAMEO+ subcategory codes

Pass any of these as subcategory (the domain’s codes). Expand a domain to see its codes.

POLITICAL — CAMEO root codes

Code	Meaning
`01`	Make public statement
`02`	Appeal
`03`	Express intent to cooperate
`04`	Consult
`05`	Engage in diplomatic cooperation
`06`	Engage in material cooperation
`07`	Provide aid
`08`	Yield
`09`	Investigate
`10`	Demand
`11`	Disapprove
`12`	Reject
`13`	Threaten
`15`	Exhibit force posture
`16`	Reduce relations
`17`	Coerce (non-violent)

Roots 14, 18, 19, 20 (protest / assault / fight / unconventional violence) are ACLED-covered and routed to the Conflict family instead.The boundary between the two families is did it happen, or was it said? An act that occurred is a Conflict (ACLED) event; a threat, demand, warning, or ultimatum is a speech act and stays in CAMEO+ POLITICAL. So “Israel struck Iran” is Conflict, while “Israel threatened to strike Iran” is 1384 under root 13. Root 13 therefore covers every threat, including threats of military force (138, 1381–1385), repression (137), and ultimatums (139) — it is not limited to non-military threats. Coercion that has been actually imposed (e.g. sanctions in force) is root 17, not 13.

ECONOMIC (EC)

Code	Meaning
`EC01`	Macroeconomic indicator release
`EC02`	Monetary policy action
`EC03`	Fiscal policy action
`EC04`	Trade policy action
`EC05`	Market stress event
`EC06`	Currency event
`EC07`	Sovereign debt event

CORPORATE (CO)

Code	Meaning
`CO01`	Merger or acquisition
`CO02`	Bankruptcy or restructuring
`CO03`	Production capacity change
`CO04`	Technology development milestone
`CO05`	Capital allocation event
`CO06`	Regulatory or legal action
`CO07`	Leadership or governance change
`CO08`	Supply chain shock

TECHNOLOGY (TE)

Code	Meaning
`TE01`	AI capability event
`TE02`	Military technology event
`TE03`	Cyber event
`TE04`	Space or satellite event
`TE05`	Strategic technology control
`TE06`	Critical tech infrastructure

INFRASTRUCTURE (IN)

Code	Meaning
`IN01`	Energy infrastructure event
`IN02`	Transport disruption
`IN03`	Supply chain disruption
`IN04`	Communications infrastructure
`IN05`	Deliberate infrastructure sabotage
`IN06`	Water infrastructure event

ENVIRONMENT (EN)

Code	Meaning
`EN01`	Geophysical hazard
`EN02`	Meteorological hazard
`EN03`	Climate event
`EN04`	Environmental pollution event
`EN05`	Environmental policy or agreement

HEALTH (HE)

Code	Meaning
`HE01`	Disease outbreak
`HE02`	Pandemic or global health emergency
`HE03`	Vaccine or treatment milestone
`HE04`	Public health policy action
`HE05`	Health system crisis

DEMOGRAPHIC (DE)

Code	Meaning
`DE01`	Mass displacement or refugee event
`DE02`	Migration event
`DE03`	Population crisis
`DE04`	Labor event
`DE05`	Urbanization or housing event

INFORMATION (IF)

Code	Meaning
`IF01`	Disinformation or influence operation
`IF02`	Information control action
`IF03`	Major leak or disclosure
`IF04`	Narrative warfare event

CRIME (CR)

Code	Meaning
`CR01`	Homicide or violent crime
`CR02`	Sexual violence or exploitation
`CR03`	Kidnapping or abduction
`CR04`	Robbery, burglary, or theft
`CR05`	Fraud or financial crime
`CR06`	Narcotics trafficking or smuggling
`CR07`	Organized crime or gang activity
`CR08`	Arrest, charge, conviction, or sentencing
`CR09`	Prison, jailbreak, or custody incident
`CR10`	Police investigation or operation

Story categories

For /api/v2/stories, filter with story_category (one per query). Each maps to one event family/domain.

`story_category`	Source
`conflict_security`	Conflict Events
`cameoplus_political`	CAMEO+ `POLITICAL`
`cameoplus_crime`	CAMEO+ `CRIME`
`cameoplus_economic`	CAMEO+ `ECONOMIC`
`cameoplus_corporate`	CAMEO+ `CORPORATE`
`cameoplus_technology`	CAMEO+ `TECHNOLOGY`
`cameoplus_infrastructure`	CAMEO+ `INFRASTRUCTURE`
`cameoplus_environment`	CAMEO+ `ENVIRONMENT`
`cameoplus_health`	CAMEO+ `HEALTH`
`cameoplus_demographic`	CAMEO+ `DEMOGRAPHIC`
`cameoplus_information`	CAMEO+ `INFORMATION`

Filtering, sorting & grouping

Parameter	Accepted values
`sort` (events, stories)	`significance` (default analyst ranking) · `recent` (freshest first)
`group_by` (`/summary`)	`date` · `country` · `region` · `continent` · `category` · `subcategory`
`confidence_profile`	`strictest` · `precise` · `balanced` · `loose`

Event metric filters

Every metric below accepts _min and _max query parameters (e.g. significance_min=0.7).

Metric (`{metric}_min` / `{metric}_max`)	Range	Meaning
`significance`	0 – 1	Composite analyst importance (drives default ranking).
`confidence`	0 – 1	Extraction / coding confidence.
`goldstein_scale`	−10 – 10	Cooperation (−) to conflict (+); see scale below.
`goldstein_severity`	0 – 10	Severity magnitude of the action.
`magnitude`	0 – 10	Intensity of the event for its own type, on its domain’s anchored ladder — conflict `min(10, 2 + 2·log₁₀(deaths))`; hazard, verbal (the CAMEO coercion ladder) and economic each on an anchored impact tier. Comparable within a domain only: a conflict 8 and an economic 8 are not the same size — rank across domains with `significance`. `null` when no severity observable was found; `null` means unknown, not zero — never coerce it to `0`.
`systemic_importance`	0 – 1	How much the wider system depends on the node this event touched — the mean of `size`, `interconnectedness` and `irreplaceability` (equal weights, per Basel BCBS G-SIB / ECB O-SII practice). A property of the node, not a count of how many states or populations are involved. A large firm is not automatically systemic; an unsubstitutable supplier is. Low base rate.
`propagation_potential`	0 – 1	The transmission conditions present now that would let a shock travel — the mean of `channel`, `coupling`, `breach`, `primed` and `(1 − containment)`, returning `0` when no live channel exists. Adapted from the ERCS barrier model (Commission Delegated Reg. (EU) 2020/2034) and Rinaldi–Peerenboom–Kelly dependency coupling. Not a probability and not a forecast of follow-on events; it carries no per-domain prior.
`market_sensitivity`	0 – 1	How much market-relevant information the event carries for a reasonable investor — `(claim_exposure + economic_bite) / 2` behind an exposure gate, `0` when no traded claim is exposed. Adapted from the reasonable-investor materiality test (TSC Industries v. Northway; Basic v. Levinson; MAR Art. 7(4)). An unsigned ordinal ranking signal — not a predicted price move, not a probability, not an expected return; it indicates no direction.

Goldstein scale. Present for all Conflict Events and for CAMEO+ POLITICAL events where meaningful; null for non-political CAMEO+ domains. +5…+10 cooperative, −4…+4 neutral/mixed, −5…−10 conflictual or coercive. Use has_fatalities=true for fatal events rather than a fatality range filter.

magnitude, systemic_importance, propagation_potential and market_sensitivity are CAMEO+ only. Conflict events carry all four as null, so adding one of these filters to a Conflict query returns an empty 200 rather than an error — the filter can only match a scored CAMEO+ row. significance and confidence are the cross-family filters. Note also that roughly 6% of CAMEO+ events have no metrics row at all; treat an absent metric as unknown, never as 0.

How to read magnitude, systemic_importance, propagation_potential and market_sensitivity. These four are rubric scores, not measurements. Read this before using any of them in a threshold, a model feature, or a customer-facing claim.

Rubric scores, not measurements. For each metric, a model reads a handful of concrete sub-factors off the source text — a fatality count, how substitutable a supplier is, whether a barrier that was holding got breached, whether a traded claim is exposed — and states a reason for each one. Fixed, published formulas then turn those sub-factors into the score. Nothing is fitted, estimated from price history, or forecast, and nothing is a black box: any value is reconstructable by a third party from the sub-factors and the published formula. The frameworks give the rubric its structure — they do not make the values empirical. magnitude follows domain severity scales (Richardson log-deaths, anchored MEPV-style on 0–10; an EM-DAT-style realized-impact tier for hazards; the CAMEO coercion ladder for speech acts). systemic_importance follows the BCBS G-SIB / ECB O-SII equal-weight indicator practice. propagation_potential follows the ERCS barrier model and the ESRB systemic-risk shape. market_sensitivity follows the reasonable-investor materiality test. We adapt these frameworks for their vocabulary and structure. None of these institutions endorses, reviews, or is connected to this work, and their use does not make our values measured. Coverage — why “measured” is the wrong word. Over 42,099 events in a 45-day window: a hard registry attribute — the observable that would make systemic_importance measured rather than judged — resolves for about 2.2% of events, and a traded instrument, behind market_sensitivity’s exposure gate, resolves for about 1.5%. For everything else the score is a judged rubric reading. Treat all four as ordinal ranking signals: use them to sort, filter and triage, not to assert a quantity about a single event. Reliability — the smallest difference worth reading. The same 59 events, coded three times with identical prompts and formulas, so everything that moved is noise:

Metric	Repeat-coding movement (mean within-event SD)	Smallest defensible single-event difference
`magnitude` (0–10)	~0.36	0.72
`systemic_importance` (0–1)	~0.03	~0.07
`propagation_potential` (0–1)	~0.03	~0.07
`market_sensitivity` (0–1)	~0.03	~0.07

Never read a single-event difference smaller than the last column. Distribution-level comparisons are far steadier than individual events, so aggregate claims hold well below these thresholds — but a claim that one event moved does not. magnitude is within-domain only. Each domain has its own anchored ladder, so a conflict magnitude of 8 and an economic magnitude of 8 are not the same “size.” Use significance — the family-scoped composite — whenever you rank events across domains. And magnitude is null when no severity observable was found: null means unknown, never zero. The four are not fully independent axes. Under the ESRB framing, market_sensitivity is a propagation channel — common exposure and confidence effects expressed in prices — so it is closer to a special case of propagation_potential than an orthogonal dimension. Both are served because market_sensitivity carries substantial independent variance and fires domain-appropriately, but do not treat the set as four independent dimensions in a model or a weighted score.

Geography

Country, region, and continent filters share one resolver across Events, Stories, Entities, and Energy.

Parameter	Accepts
`country`	Plain-English name (`United States`), ISO-3 (`USA`), or legacy FIPS alias. Outputs normalize to country names.
`continent`	`Africa` · `Asia` · `Europe` · `North America` · `South America` · `Oceania`
`region`	`Africa` · `Asia` · `Middle East` · `Northern Africa` · `Western Africa` · `Eastern Africa` · `Middle Africa` · `Southern Africa` · `Europe` · `Eastern Europe` · `South Asia` · `Southeast Asia` · `East Asia` · `Central Asia` · `North America` · `Central America` · `Caribbean` · `South America` · `Oceania`
`admin1`	State / province within a country. Discover per-country with `GET /api/v2/geo/admin1` (see Geography) — there is no global admin1 catalog.
`bbox`	Viewport `lat_min,lon_min,lat_max,lon_max` (lat ∈ [−90, 90], lon ∈ [−180, 180]).

Energy vocabularies

For /api/v2/energy/*.

Trackers & capacity units

Pass one or more tracker values (comma-separated).

`tracker`	Label	Capacity unit
`coal_plants`	Coal Plants	MW
`coal_mines`	Coal Mines	Mtpa
`coal_terminals`	Coal Terminals	Mt
`oil_gas_plants`	Oil & Gas Plants	MW
`oil_gas_extraction`	Oil & Gas Extraction	—
`lng_terminals`	LNG Terminals	Mtpa
`nuclear`	Nuclear	MW
`geothermal`	Geothermal	MW
`bioenergy`	Bioenergy	MW
`hydropower`	Hydropower	MW
`solar`	Solar	MW
`wind`	Wind	MW
`gas_pipelines`	Gas Pipelines	Bcm/y
`oil_pipelines`	Oil & NGL Pipelines	bpd
`lng_carriers`	LNG Carriers	cbm

Only MW-denominated trackers (coal_plants, oil_gas_plants, nuclear, geothermal, bioenergy, hydropower, solar, wind) are safe to sum across trackers in a single rollup.

Energy enums

Parameter	Accepted values
`sort`	`capacity_desc` · `capacity_asc` · `start_year_desc` · `start_year_asc` · `recent` · `name`
`asset_class`	`fixed` · `mobile` · `all`
`group_by` (`/summary`)	`country` · `region` · `continent` · `tracker` · `status` · `start_year_decade` · `fuel` · `tier`
`status`	`operating` · `construction` · `proposed` · `cancelled` · `retired` (comma-separated; raw GEM statuses normalize into these)
`fuel`	tracker-native fuel values (comma-separated) — the fuel strings each GEM tracker reports
`tier`	within-tracker tier values (comma-separated), e.g. pipelines use `main` · `utility` · `distribution`
`bbox`	`lat_min,lon_min,lat_max,lon_max`
`near`	`lat,lon,radius_km` (radius_km ≤ 20000)

Maritime chokepoints

Generally available — plan-gated on can_use_maritime; keys without it get a 403 PLAN_REQUIRED.

The Maritime API filters by chokepoint: hormuz · bab_el_mandeb · malacca · suez · panama · bosphorus · gibraltar · dover · kerch · taiwan · danish_straits Other maritime parameters:

Parameter	Accepted values
`bucket` (activity)	`hour` · `day`
`cell_deg` (density)	grid cell size `0.01`–`1` (default `0.05`)
`bbox`	`minLon,minLat,maxLon,maxLat` — longitude-first (the opposite axis order from Events/Energy)
`near` / `near_gem_id`	proximity center + `radius_km` (1–2000)

Languages

Source-language filters (languages, comma-separated ISO 639-1 codes) on Events, Stories, Entity Tone, and Share of Voice. Any of the 62 recognized codes is accepted; these 24 are the most-covered (also the default filter options):


`en` English	`ar` Arabic	`zh` Chinese	`es` Spanish	`fr` French	`de` German
`ru` Russian	`pt` Portuguese	`it` Italian	`tr` Turkish	`fa` Persian	`ja` Japanese
`ko` Korean	`hi` Hindi	`id` Indonesian	`uk` Ukrainian	`ro` Romanian	`pl` Polish
`nl` Dutch	`sv` Swedish	`el` Greek	`he` Hebrew	`th` Thai	`vi` Vietnamese

All 62 recognized source languages

en English · ar Arabic · zh Chinese · es Spanish · fr French · de German · ru Russian · pt Portuguese · it Italian · tr Turkish · fa Persian · ja Japanese · ko Korean · hi Hindi · id Indonesian · uk Ukrainian · ro Romanian · pl Polish · nl Dutch · sv Swedish · el Greek · he Hebrew · th Thai · vi Vietnamese · sr Serbian · bg Bulgarian · hr Croatian · cs Czech · hu Hungarian · sk Slovak · bn Bengali · ur Urdu · ta Tamil · sq Albanian · az Azerbaijani · ka Georgian · hy Armenian · fi Finnish · da Danish · no Norwegian · bs Bosnian · sl Slovenian · mk Macedonian · sw Swahili · lt Lithuanian · lv Latvian · et Estonian · is Icelandic · mt Maltese · ga Irish · ml Malayalam · kn Kannada · te Telugu · mr Marathi · gu Gujarati · pa Punjabi · ne Nepali · si Sinhala · my Burmese · km Khmer · lo Lao · am Amharic

Entities

Parameter	Accepted values
`type`	`person` · `organization`
`scope` (`/entities/resolve`)	`media` (news-resolved entities) · `reference` (GEM owners, SEC/EDGAR filers, screening lists, China financiers) · `all` (everything, deduped)

Media Intelligence

Generally available — plan-gated: Entity Tone on can_use_tone, Share of Voice on can_use_share_of_voice; keys without the flag get a 403 PLAN_REQUIRED. Social signal (/api/v2/social) is the one surface still in admin-only preview. Entity Tone & Share of Voice measure press coverage, not public opinion.

Parameter	Accepted values
`quality` (entity tone)	`production_ready` (default) · `reviewable` · `all`
`bucket` (entity tone)	`day` · `week` · `month`
Share-of-Voice denominator	at least one of `query` · `topic` · `category` · `country` · `region` · `languages` · `source_set` (semantic `query` preferred)

Briefs

Parameter	Accepted values
`time_window`	`6h` · `24h` · `72h` · `7d` · `30d`
`baseline_window`	`7d` · `14d` · `30d`
`audience`	`executive` · `analyst` · `operator`
`depth`	`skim` (first-order) · `standard` (second-order) · `detailed` (third-order)
`brief_type`	`monitoring_brief`

Filings

Generally available — plan-gated on can_use_filings; keys without it get a 403 PLAN_REQUIRED. SEC EDGAR is public domain (cite the SEC); relation edges + entity resolution are GDELT Cloud derived.

Parameter	Accepted values
`form_type`	`10-K` · `10-Q` · `8-K` · `13F-HR` · `SCHEDULE 13D` · `SCHEDULE 13G` · `3` · `4` · `5` · `DEF 14A` · `S-1` · `20-F` · `6-K` (exact EDGAR strings)
`rel_type`	`subsidiary` · `supplier` · `customer` · `counterparty` · `partner` · `jurisdiction_exposure`
`event_type` (material 8-K events)	`acquisition` · `material_agreement` · `executive_change` · `results` · `guidance` · `other`
`sort`	`recent` · `filer`
`group_by` (`/summary`)	`form_type` · `date` · `filer`

Macro Finance

Generally available — plan-gated on can_use_macro; keys without it get a 403 PLAN_REQUIRED. Sourced from FRED / ALFRED; carry the FRED non-endorsement notice.

Parameter	Accepted values
`frequency`	`D` · `W` · `BW` · `M` · `Q` · `SA` · `A` (FRED frequency codes — Daily, Weekly, Biweekly, Monthly, Quarterly, Semiannual, Annual)
`agency`	Source agency, filtered against the catalog. These return data — `BLS` · `BEA` · `FRB` (Federal Reserve — incl. Treasury yields, H.15) · `CBOE` · `Census` · `EIA` · `FHFA` · `Freddie Mac` · `U. Michigan`.
`as_of`	vintage date `YYYY-MM-DD` — values as known on/before that date (ALFRED point-in-time)

Reference & Screening

Generally available — plan-gated per surface: screening lists + counterparty match on can_use_screening, ownership-chain exposure on can_use_exposure, China development finance on can_use_china. Keys without the flag get a 403 PLAN_REQUIRED.

Parameter	Accepted values
`lens` (exposure)	`sanctions` · `china` · `state_owned`
`subject` (exposure)	`assets` · `entities`
`group_by` (exposure)	`none` · `country` · `tracker`
`sort` (exposure)	`capacity_desc` · `stake_desc`
`sort` (lists / screening)	`name` · `recent`
`change_type` (lists/changes)	`added` · `removed` · `changed`
`sort` (china projects)	`amount_desc` · `recent`

Putting it together

# Conflict protests in Sub-Saharan regions, high significance, last 14 days
curl "https://gdeltcloud.com/api/v2/events?event_family=conflict&category=Protests&region=Western%20Africa&significance_min=0.6&days=14" \
  -H "Authorization: Bearer gdelt_sk_..."

# CAMEO+ monetary-policy events (EC02), grouped by country
curl "https://gdeltcloud.com/api/v2/events/summary?event_family=cameoplus&category=ECONOMIC&subcategory=EC02&group_by=country&days=30" \
  -H "Authorization: Bearer gdelt_sk_..."

# Corporate-domain stories, freshest first
curl "https://gdeltcloud.com/api/v2/stories?story_category=cameoplus_corporate&sort=recent&days=7" \
  -H "Authorization: Bearer gdelt_sk_..."

Facilities

Events

Stories

Entities

Geography

Reference Data

Government

Energy

Briefs

Filings

Macro Finance

Maritime

Media Intelligence

Screening and Reference

China

Unified Search

AI Compute

Taxonomy & Codes

Event families

Event categories & subcategories

Conflict event types

CAMEO+ domains

CAMEO+ subcategory codes

Story categories

Filtering, sorting & grouping

Event metric filters

Geography

Energy vocabularies

Trackers & capacity units

Energy enums

Maritime chokepoints

Languages

Entities

Media Intelligence

Briefs

Filings

Macro Finance

Reference & Screening

Putting it together

​Event families

​Event categories & subcategories

​Conflict event types

​CAMEO+ domains

​CAMEO+ subcategory codes

​Story categories

​Filtering, sorting & grouping

​Event metric filters

​Geography

​Energy vocabularies

​Trackers & capacity units

​Energy enums

​Maritime chokepoints

​Languages

​Entities

​Media Intelligence

​Briefs

​Filings

​Macro Finance

​Reference & Screening

​Putting it together

Event families

Event categories & subcategories

Conflict event types

CAMEO+ domains

CAMEO+ subcategory codes

Story categories

Filtering, sorting & grouping

Event metric filters

Geography

Energy vocabularies

Trackers & capacity units

Energy enums

Maritime chokepoints

Languages

Entities

Media Intelligence

Briefs

Filings

Macro Finance

Reference & Screening

Putting it together