Bulk events schema

Bulk downloads hand you the same coded events the API serves, as files instead of pages of JSON.

Getting the files

Sign in and open Bulk Data Download. Every plan can see the page: every file for every period, with its sha256, byte size and row count, a per-period completeness label so you can tell which dates are settled before you load one, and a summary of what each file contains. Downloading the files is included on the Intelligence, Enterprise and Academic plans. If you need this automated rather than downloaded by hand, tell us — a programmatic manifest exists and we will publish it as a supported contract once every period exports cleanly.

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.

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.

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, the CAMEO+ family carries no fatalities, and a story with no coded events has no fatality count at all. 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 three-valued booleans such as civilian_targeting: 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.

Events

One row per event, 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.

Summary statistics

Every published file carries a summary of its own contents, computed by the run that cut it and shown on Bulk Data Download. It is there so you can see what is in a period before downloading it. Value counts — the most frequent values, with how many distinct ones exist and how many rows carry none. An absent value is reported separately and never counted as a category.

Dimension	Column	Values published
Taxonomy family	`event_family`	top 5
Category	`category`	top 25
Subcategory	`subcategory`	top 25
Country	`country_iso3`	top 25
Acting party	`source_actor`	top 25
Acting party country	`source_actor_country_iso3`	top 15
Receiving party	`target_actor`	top 25
Receiving party country	`target_actor_country_iso3`	top 15
Entities	`entity_names`	top 25
Goldstein quad class	`quad_class`	top 4
Civilian targeting	`civilian_targeting`	top 2

Distributions — count of rows carrying the metric, minimum, the 10th, 25th, 50th, 75th and 90th percentiles, maximum and mean. Quantiles are exact and inclusive-interpolated, the same convention pandas and Excel use, so you can reproduce them from the file you downloaded.

Metric	Column	Total published
Significance	`significance`	no
Goldstein scale	`goldstein_scale`	no
Magnitude	`magnitude`	no
Systemic importance	`systemic_importance`	no
Propagation potential	`propagation_potential`	no
Market sensitivity	`market_sensitivity`	no
Coder confidence	`confidence`	no
Fatalities	`fatalities`	yes
Articles per event	`article_count`	yes

Percentiles are computed over the rows where the metric is PRESENT, so a metric that applies to part of the file describes that part — it is never padded with zeroes to fill the rest.

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

Monitors

Products

Data

How the data is made

Use cases

Getting the files

Files

Reading the two formats

Coverage

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.

Events

Summary statistics

How the export differs from the warehouse

​Getting the files

​Files

​Reading the two formats

​Coverage

​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.

​Events

​Summary statistics

​How the export differs from the warehouse

Getting the files

Files

Reading the two formats

Coverage

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.

Events

Summary statistics

How the export differs from the warehouse