GDELT Cloud Docs — Global Event Data API & MCP

Bulk downloads hand you the same coded events the API serves, as files instead of pages of JSON. One file per calendar month, plus a rolling full-history file, in two formats.

Files


Formats	Parquet (`.parquet`) and gzipped CSV (`.csv.gz`) — identical rows, identical column names
Partitioning	One file per calendar month, named `<dataset>_YYYY-MM`, plus `<dataset>_all`
Integrity	Every file publishes a `sha256`, a byte size and a row count. Check the digest before loading
Ordering	Deterministic. Re-exporting an unchanged month reproduces the same bytes and the same digest

Reading the two formats

Parquet carries real types: a null is a null, an array is a LIST, and a timestamp is a TIMESTAMP. Prefer it if your tooling can read it. CSV has neither nulls nor arrays, so two conventions apply and they are the only differences between the formats:

Array columns are JSON arrays, written as a single quoted field — parse them with your JSON reader, not by splitting on a delimiter. A title containing a comma would break the row otherwise, and titles contain commas.
An empty field is a null. CSV cannot distinguish “no value” from “the empty string”, and in this data the distinction matters: see the note on metrics below.

Nulls are information, not gaps

A null metric does not mean zero. It means the column does not apply to that row: the conflict family carries no magnitude, systemic_importance, propagation_potential or market_sensitivity, and the CAMEO+ family carries no fatalities. Coalescing these to 0 on load will invent measurements that were never taken, and any average you compute afterwards will be wrong in a direction you cannot recover. The same applies to civilian_targeting, which is deliberately three-valued: true where a coder judged civilians were targeted, false where a coder judged they were not, and null where no coder evaluated the question at all.

Backtesting: what you can and cannot claim as-of

These files support a real point-in-time filter, and they do not support a full vintage. The difference decides whether a backtest is sound, so it is worth being exact.

The event SET is point-in-time. Use `coded_at`.

coded_at is the moment our coder produced the event, recorded per row and populated on 100% of rows. Every event is derived from articles published before it, and those articles are cited in source_urls, so the claim is checkable rather than asserted. That means WHERE coded_at <= T gives you the set of events that existed in our database at time T. It is a filter on a recorded fact, not a reconstruction. It is the same lever the API exposes as observed_start / observed_end. Measured over July 2026 (42,603 events): 79.4% were coded within a day of the event date, 98.6% within two days, 99.2% within seven. Median lag 16 hours, 90th percentile 33. Only 0.61% of July events were coded after July ended. So do not filter a backtest on event_date alone. Doing so hands your strategy events it could not have seen — about 1.4% of any given month arrived more than two days late, and the tail runs to weeks.

The VALUES in a row are not vintaged.

The row carries what we know now, not what we knew at coded_at. A later article can sharpen the location, the entity resolver can attach a name it could not resolve at the time, an adjudicator can merge the event with another. The settle overwrites in place; there is no per-field history. So coded_at <= T gives you the right ROWS with today’s VALUES. For most event-driven work that is fine — what happened, where, to whom and when we knew it are all stable. It matters if your signal keys on a revisable field: the metric scores, entity_names, or incident_uid, which is assigned by an adjudicator that runs after coding. One consequence worth designing for: event_uid is a stable hash of the cluster, but event_date is the coder’s judgement and is re-derived on a re-code. An event whose date moves therefore moves BETWEEN monthly files rather than changing position within one. Match on event_uid across files, not on event_uid within a month.

Coverage

Each file records the settled dates it covers against the calendar days in its period. A month is only complete when those two agree; the manifest publishes both, so a partial month is visible rather than silently short.

Events

One row per record, ordered by event_date, event_uid. Every column below is a field /api/v2/events returns — the file and the endpoint read the same table, so a row in the file and the same row from the API agree field for field.

Column	Parquet	CSV	Nullable	Description
`event_uid`	UTF8	text	no	Stable event identifier. Primary key with event_date; the same id /api/v2/events/{id} serves.
`event_date`	DATE	YYYY-MM-DD	no	The day the event occurred — the content clock, not the day we coded it.
`incident_uid`	UTF8	text	no	Shared by events judged to be the same real-world incident. Defaults to the event’s own uid when nothing was adjudicated, so grouping by it is always safe.
`event_family`	UTF8	text	no	Which taxonomy coded it: “cameoplus” or “conflict” (ACLED methodology).
`category`	UTF8	text	yes	Top-level category — the CAMEO+ domain, or the ACLED event type.
`subcategory`	UTF8	text	yes	Taxonomy IDENTIFIER, and exactly what ?subcategory= accepts. A CAMEO+ code (“EC04”, “042”) or an ACLED sub-event type (“Peaceful protest”).
`subcategory_label`	UTF8	text	yes	The human-readable name for subcategory. Equal to subcategory for the conflict family, where the label IS the identifier.
`event_code`	UTF8	text	yes	Raw CAMEO+ code. Empty on conflict-family rows.
`title`	UTF8	text	yes	Event title.
`summary`	UTF8	text	yes	One-paragraph description of the event.
`url`	UTF8	text	yes	Public GDELT Cloud page for this event — open it to see the evidence behind the row.
`country`	UTF8	text	yes	Country, as an English display name.
`country_iso3`	UTF8	text	yes	ISO 3166-1 alpha-3. Join on this, not on country.
`region`	UTF8	text	yes	Sub-region label.
`admin1`	UTF8	text	yes	First-level administrative division (state, province, oblast).
`location`	UTF8	text	yes	Most specific place name resolved for the event.
`latitude`	DOUBLE	decimal	yes	Latitude, WGS84.
`longitude`	DOUBLE	decimal	yes	Longitude, WGS84.
`geo_precision`	INT	integer	yes	How precisely the location is known: 1 exact, 2 admin area, 3 country. Read this before mapping the coordinates.
`source_actor`	UTF8	text	yes	CAMEO+ acting party. On conflict rows this is actor1 — a party to the clash, not an initiator.
`source_actor_country_iso3`	UTF8	text	yes	Acting party’s country, ISO3.
`target_actor`	UTF8	text	yes	CAMEO+ receiving party. On conflict rows this is actor2.
`target_actor_country_iso3`	UTF8	text	yes	Receiving party’s country, ISO3.
`significance`	DOUBLE	decimal	yes	Composite importance, 0–1. Comparable WITHIN a family; not calibrated across families.
`goldstein_scale`	DOUBLE	decimal	yes	Goldstein cooperation/conflict scale, −10 to +10. CAMEO political and the conflict family only.
`quad_class`	UTF8	text	yes	Goldstein quad class as a label (verbal/material × cooperation/conflict).
`magnitude`	DOUBLE	decimal	yes	How large the event is in its own terms, 0–10. CAMEO+ only.
`fatalities`	INT	integer	yes	Reported deaths. Conflict family only — NULL on CAMEO+ rows, never 0.
`civilian_targeting`	BOOLEAN	true / false	yes	True where the coder judged civilians were targeted, false where it judged they were not, NULL where no coder evaluated it.
`systemic_importance`	DOUBLE	decimal	yes	How central the affected node is, 0–1. CAMEO+ only.
`propagation_potential`	DOUBLE	decimal	yes	How likely effects are to spread, 0–1. CAMEO+ only.
`market_sensitivity`	DOUBLE	decimal	yes	How exposed markets are to this event, 0–1. CAMEO+ only.
`confidence`	DOUBLE	decimal	yes	Coder confidence in the classification, 0–1. Well calibrated above ~0.8 and NOT below it — do not threshold on low values.
`metric_version`	UTF8	text	yes	Which metric definition produced the scores and metric_inputs on this row. “v2-2026-07-24” carries a per-sub-factor `why`; earlier rows are a thinner shape with values only.
`metric_inputs`	UTF8 (JSON)	JSON object	yes	JSON: every metric sub-factor with its value and — from v2-2026-07-24 — the coder’s stated reason. This is how magnitude, systemic_importance, propagation_potential and market_sensitivity were arrived at — read it to audit a score rather than trusting it.
`article_count`	INT	integer	yes	Articles in the story this event was coded from.
`source_urls`	LIST<UTF8>	JSON array	no	Article URLs the coder read to produce this event. The evidence, so a row can be checked.
`story_id`	UTF8	text	yes	The story this event was coded from.
`entity_names`	LIST<UTF8>	JSON array	no	Resolved entities linked to this event, after the identity arbiter collapses duplicates.
`coded_at`	TIMESTAMP	YYYY-MM-DD hh:mm:ss (UTC)	yes	UTC timestamp when the coder produced this event — the processing clock.
`as_of`	TIMESTAMP	YYYY-MM-DD hh:mm:ss (UTC)	no	What this row knew, and when. Events are NOT vintaged — the next settle overwrites — so this is a currency ceiling, not a point-in-time snapshot.

41 columns, 34 of them nullable.

How the export differs from the warehouse

Most columns ship exactly as stored. Two conventions apply to all of them, and a handful of columns are computed at export time. An absent value is null, never an empty string. Wherever a value is missing the file carries a true null in Parquet and an empty field in CSV, so an IS NULL check finds every absent value. Column names are the API’s names, so a row in the file and the same row from /api/v2/events agree field for field.

Column	What to know
`incident_uid`	Matches the API exactly (schema 142 serve rule). The stored column is empty on unadjudicated rows; publishing that as NULL would collapse every unadjudicated event into one group.
`subcategory`	DERIVED. The stored column holds a retired composite form on partitions settled before 2026-08-17.
`subcategory_label`	DERIVED from the same taxonomy map the API uses.
`civilian_targeting`	Stored as a tri-state UInt8. The CAST is load-bearing — a bare `!= 0` yields UInt8, which Parquet writes as an INTEGER, so the file would ship 1/0 against a dictionary promising BOOLEAN.
`article_count`	Renamed from canonical_cluster_article_count — the stored name is internal vocabulary.
`story_id`	An event carries exactly one story (the canonical cluster), so the stored array is flattened to a scalar.
`entity_names`	Renamed from entity_ref_names — “ref” is internal vocabulary. The parallel id/type/id_space/wikipedia arrays are API-only; a flat file wants the names.

Start here

Use cases

Data

How the data is made

Bulk export schema

Files

Reading the two formats

Nulls are information, not gaps

Backtesting: what you can and cannot claim as-of

The event SET is point-in-time. Use `coded_at`.

The VALUES in a row are not vintaged.

Coverage

Events

How the export differs from the warehouse

​Files

​Reading the two formats

​Nulls are information, not gaps

​Backtesting: what you can and cannot claim as-of

​The event SET is point-in-time. Use coded_at.

​The VALUES in a row are not vintaged.

​Coverage

​Events

​How the export differs from the warehouse

Files

Reading the two formats

Nulls are information, not gaps

Backtesting: what you can and cannot claim as-of

The event SET is point-in-time. Use `coded_at`.

The VALUES in a row are not vintaged.

Coverage

Events

How the export differs from the warehouse