GDELT variable dictionary · Comparative Politics

Three tables, one ecosystem

GDELT (Global Data on Events, Location, and Tone) updates every 15 minutes a repository of news from press, radio and television in more than one hundred languages. The data is organised into three related tables:

Event Database (v2.0). Dyadic interactions coded as subject-action-object: who did what to whom, where and when.
Global Knowledge Graph (GKG v2). Themes, entities, sentiment, quotations and concept counts extracted from the full document.
Event Mentions Table. Connects each event with later news items that mention it.

The three can be joined through common identifiers. The key is to understand what each level represents: the event is the coded action; the GKG is the thematic context of the document; mentions are the event’s media life.

Event Database v2.0

Each event record includes 61 columns organised in five blocks: identifiers and dates, actor attributes, CAMEO action, media impact metrics and geolocation.

Actors

An actor is not just a country. It is a string of up to ten characters combining geographic affiliation, ethnic group, religion and political role. For example, USACOPGOV breaks down into:

USA: country.
COP: role (police forces).
GOV: actor type (government).

CAMEO action

The EventCode classifies the interaction in a three-level taxonomic tree:

EventRootCode: general category, for example 14 (protest).
EventBaseCode: subcategory, for example 141 (demonstrate or strike).
EventCode: specific action, for example 1411 (protest against state repression).

Media metrics

NumMentions: number of times the event appears in articles during the 15-minute cycle.
NumSources: number of distinct outlets publishing the story.
AvgTone: affective tone of the text, on a scale of roughly -100 to +100.

Geolocation

GDELT assigns coordinates to the event (ActionGeo) and to each actor (Actor1Geo, Actor2Geo). The type field indicates the resolution level: country, province, city or specific point. Coordinates enable GIS analysis and subnational aggregation.

Global Knowledge Graph

The GKG processes the full document, not just the action triple. Its main fields include:

V2Themes: list of taxonomic themes such as TAX_ETHNICITY, CRISISLEX_CRISIS_RESPONSE, AUTOCRACY, ELECTION or MILITARY.
V2Persons and V2Organizations: names of public figures and organisations with their position in the document.
GCAM: more than twenty psychological and analytical dictionaries (LIWC, WordNet, Regressive Imagery Dictionary) measuring emotions, anxiety, certainty or framing.
V2Quotations: quoted statements with the speaker, the quotation verb and the text.

Mentions table

The mentions table tracks the media life cycle of an event:

GLOBALEVENTID: connects to the Event Database.
MentionTimeDate: when the outlet cited the event.
SentenceID: sentence in the article where the mention appears.
Confidence: the algorithm’s certainty that the mention matches the original event.

CAMEO, QuadClass and Goldstein

CAMEO classifies actions into four macro-categories (QuadClass) and assigns a conflict or cooperation value (GoldsteinScale, from -10 to +10):

QuadClass	Type	Goldstein range	Examples
1	Verbal cooperation	+1.0 to +6.0	Statements, negotiations, diplomatic visits.
2	Material cooperation	+3.0 to +10.0	Humanitarian aid, military cooperation, agreements.
3	Verbal conflict	-1.0 to -5.0	Accusations, threats, calls for resignation.
4	Material conflict	-5.0 to -10.0	Protests, repression, physical violence, states of siege.

The scale is a theoretical weighting, not an empirical measure of harm. It is used to build stability or conflict indices, always with caution.

Variable dictionary

Variable	Table	Type	Use
`GLOBALEVENTID`	events	integer	Primary key to join events and mentions.
`SQLDATE`	events	integer `YYYYMMDD`	Temporal filtering and grouping.
`Actor1Code`	events	text	Geographic, ethnic, religious or role identity of the actor.
`Actor1Name`	events	text	Plain name of the actor.
`Actor1CountryCode`	events	ISO-3 text	Territorial affiliation of the actor.
`EventCode`	events	CAMEO text	Specific action.
`QuadClass`	events	integer 1-4	Macro-category of cooperation or conflict.
`GoldsteinScale`	events	decimal -10 to +10	Theoretical impact on stability.
`NumMentions`	events	integer	Intensity of event coverage.
`AvgTone`	events	decimal -100 to +100	Average affective tone.
`ActionGeo_Lat` / `ActionGeo_Long`	events	decimal	Event coordinates.
`GKGRECORDID`	gkg	text	Document identifier in the GKG.
`V2Themes`	gkg	text	Taxonomic themes of the document.
`GCAM`	gkg	text	Psychological and framing dictionaries.
`V2Quotations`	gkg	text	Quoted statements with speaker and verb.
`MentionTimeDate`	mentions	date	Time of the event mention.

Good practices

Normalise event frequency by the volume of news for the country-year. Without normalisation, a change in the number of sources looks like a change in conflict.
Triangulate GDELT with manually curated datasets (ACLED, ICEWS, SCAD) when the design allows.
Treat the 2014 update as a series break.
Do not read a fall in events as pacification: it may be censorship or lower coverage.
Document the version, query and download date.