Skip to main content

​
Overview

GDELT uses standardized code systems for precise filtering of actors, events, locations, and themes. Understanding these codes is essential for building effective queries.
Access code references programmatically using the get_resource tool or via MCP resource URIs (gdelt://codes/*).

​
Code categories

Country Codes

CAMEO & FIPSActor filtering (ISO-3) vs Location filtering (FIPS 2-char)

Actor Codes

Types, Groups, IdentityGOV, MIL, NGO, ethnic, religious affiliations

Event Codes

CAMEO Taxonomy01-20 root codes for event classification

Theme Codes

Topics & SubjectsENV_, ECON_, CONFLICT_, HEALTH_

​
Country codes

​
CAMEO country codes (ISO-3)

ISO-3 country codes for filtering WHO (actors) in events.
Use with:
  • actor1_country_code in gdelt_events
  • actor2_country_code in gdelt_events
Format: 3-character ISO codes (USA, CHN, GBR, FRA, RUS, etc.)Example query:
SELECT day, actor1_name, event_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND actor1_country_code = 'USA'
    AND actor2_country_code = 'CHN'
LIMIT 100
Common codes:
  • USA - United States
  • CHN - China
  • RUS - Russia
  • GBR - United Kingdom
  • FRA - France
  • DEU - Germany
  • JPN - Japan
  • IND - India
  • BRA - Brazil
  • CAN - Canada
  • AUS - Australia
  • KOR - South Korea
  • MEX - Mexico
  • IDN - Indonesia
  • TUR - Turkey
  • SAU - Saudi Arabia
  • IRN - Iran
  • ISR - Israel
  • UKR - Ukraine
  • POL - Poland
Resource URI: gdelt://codes/cameo-country
CAMEO (ISO-3) codes are for WHO (actors). Don’t confuse with FIPS codes which are for WHERE (locations).

​
FIPS country codes (2-char)

FIPS 2-character country codes for filtering WHERE (event locations).
Use with:
  • action_geo_country_code in gdelt_events (where event happened)
  • actor1_geo_country_code in gdelt_events (where actor1 is from)
  • actor2_geo_country_code in gdelt_events (where actor2 is from)
  • country_code in gdelt_gkg_locations_extracted
Format: 2-character FIPS codes (US, CH, UK, FR, RS, etc.)Example query:
SELECT day, actor1_name, action_geo_full_name, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND action_geo_country_code = 'UK'
LIMIT 100
Common codes:
  • US - United States
  • CH - China
  • RS - Russia
  • UK - United Kingdom
  • FR - France
  • GM - Germany
  • JA - Japan
  • IN - India
  • BR - Brazil
  • CA - Canada
  • AS - Australia
  • KS - South Korea
  • MX - Mexico
  • ID - Indonesia
  • TU - Turkey
  • SA - Saudi Arabia
  • IR - Iran
  • IS - Israel
  • UP - Ukraine
  • PL - Poland
Resource URI: gdelt://codes/fips-country
Rule of thumb: CAMEO (ISO-3) for WHO, FIPS (2-char) for WHERE

​
Actor classification codes

​
CAMEO type codes

Actor type codes classify organizations and individuals by role.
Use with:
  • actor*_type1_code (primary type)
  • actor*_type2_code (secondary type)
  • actor*_type3_code (tertiary type)
Major categories:
  • GOV - Government (general)
  • GOVMIL - Military/Defense
  • GOVCOP - Police/Law enforcement
  • GOVLEG - Legislature/Parliament
  • GOVJUD - Judiciary/Courts
  • GOVEDU - Education ministry
  • GOVHLT - Health ministry
  • GOVCCE - Central bank/Finance ministry
  • MIL - Military (not government)
  • REB - Rebels/Armed opposition
  • OPP - Opposition party/Dissidents
  • PTY - Political party
  • COP - Police (not government)
  • JUD - Judiciary (not government)
  • SPY - Intelligence/Security services
  • MED - Media
  • EDU - Education institution
  • BUS - Business/Corporation
  • CRM - Criminal
  • CVL - Civilian/General population
  • NGO - Non-governmental organization
  • IGO - Inter-governmental organization
  • SET - Settler
  • REF - Refugee/Displaced person
  • HLH - Health/Medical
  • LAB - Labor union
  • AGR - Agriculture
  • ELI - Elite/Wealthy
  • REL - Religious organization
  • ENV - Environmental organization
Example query:
SELECT day, actor1_name, actor1_type1_code, event_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND actor1_type1_code = 'MIL'
    AND event_root_code IN ('18', '19')
LIMIT 100
Resource URI: gdelt://codes/cameo-type
Multiple type codes provide granularity. Start with type1, add type2/type3 for precision.

​
CAMEO known groups

Codes for international organizations and known groups.
Use with:
  • actor*_known_group_code in gdelt_events
High precision, low recall. Only populated when organization is explicitly identified.
Major groups:
  • NATO - North Atlantic Treaty Organization
  • UN - United Nations
  • UNSC - UN Security Council
  • EU - European Union
  • ECON - European Community
  • ARAB - Arab League
  • OPEC - OPEC
  • ASEAN - Association of Southeast Asian Nations
  • OAS - Organization of American States
  • OAU - Organization of African Unity (now African Union)
  • AU - African Union
  • BRICS - Brazil, Russia, India, China, South Africa
  • G7 - Group of Seven
  • G20 - Group of Twenty
  • IMF - International Monetary Fund
  • WB - World Bank
  • WTO - World Trade Organization
  • WHO - World Health Organization
  • IAEA - International Atomic Energy Agency
  • ICRC - International Committee of the Red Cross
  • AMNESTY - Amnesty International
  • HRW - Human Rights Watch
  • TALIBAN - Taliban
  • ALQAEDA - Al-Qaeda
  • ISIS - Islamic State
Example query:
SELECT day, actor1_name, actor2_name, event_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND (actor1_known_group_code = 'NATO' OR actor2_known_group_code = 'NATO')
LIMIT 100
Resource URI: gdelt://codes/cameo-known-groups

​
CAMEO ethnic codes

Ethnic group classification codes for identity-based filtering.
Use with:
  • actor*_ethnic_code in gdelt_events
Sparse field. Use as secondary filter, not primary filter.
Common codes:
  • ARAB - Arab
  • KURD - Kurdish
  • HAN - Han Chinese
  • UIGHUR - Uighur
  • TIBETAN - Tibetan
  • HUTU - Hutu
  • TUTSI - Tutsi
  • TAMIL - Tamil
  • ROMA - Roma/Romani
  • JEWISH - Jewish
  • HISPANIC - Hispanic/Latino
  • AFRICAN - African/Black
  • ASIAN - Asian
  • CAUCASIAN - Caucasian/White
  • INDIGENOUS - Indigenous peoples
Example query:
SELECT day, actor1_name, actor1_ethnic_code, event_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 30 DAY
    AND actor1_ethnic_code IN ('KURD', 'ARAB')
    AND event_root_code = '14'
LIMIT 100
Resource URI: gdelt://codes/cameo-ethnic

​
CAMEO religion codes

Religious affiliation codes for faith-based filtering.
Use with:
  • actor*_religion1_code (primary affiliation)
  • actor*_religion2_code (secondary affiliation)
Sparse field. Use as secondary filter, not primary filter.
Common codes:
  • MOS - Muslim/Islamic
  • SUN - Sunni Islam
  • SHI - Shia Islam
  • CHR - Christian
  • CAT - Catholic
  • PTR - Protestant
  • ORT - Orthodox Christian
  • JEW - Jewish
  • HIN - Hindu
  • BUD - Buddhist
  • SIK - Sikh
  • DRUZE - Druze
  • BAH - Baha’i
Example query:
SELECT day, actor1_name, actor1_religion1_code, event_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 30 DAY
    AND actor1_religion1_code IN ('SUN', 'SHI')
LIMIT 100
Resource URI: gdelt://codes/cameo-religion

​
Event classification

​
CAMEO event codes

Complete CAMEO event taxonomy with 20 root codes and hundreds of subcodes.
01 - MAKE PUBLIC STATEMENT
  • Appeal, demand, comment, or public declaration
  • Example: 010 (Make statement), 011 (Appeal), 012 (Express intent)
02 - APPEAL
  • Request, plead, appeal for help or support
  • Example: 020 (Appeal), 021 (Appeal for material cooperation), 025 (Appeal to yield)
03 - EXPRESS INTENT TO COOPERATE
  • Promise future cooperation or assistance
  • Example: 030 (Express intent to cooperate), 031 (Express intent to engage in material cooperation)
04 - CONSULT
  • Discussion, negotiation, consultation
  • Example: 040 (Consult), 041 (Discuss by telephone), 042 (Make a visit)
05 - ENGAGE IN DIPLOMATIC COOPERATION
  • Diplomatic meetings, treaties, agreements
  • Example: 050 (Engage in diplomatic cooperation), 051 (Praise or endorse), 052 (Defend)
06 - ENGAGE IN MATERIAL COOPERATION
  • Provide material support, resources, assistance
  • Example: 060 (Engage in material cooperation), 061 (Cooperate economically), 062 (Cooperate militarily)
07 - PROVIDE AID
  • Humanitarian, economic, or military aid
  • Example: 070 (Provide aid), 071 (Provide economic aid), 072 (Provide military aid)
08 - YIELD
  • Surrender, capitulate, retreat
  • Example: 080 (Yield), 081 (Ease restrictions), 086 (Retreat or surrender)
09 - INVESTIGATE
  • Inquiry, investigation, search
  • Example: 090 (Investigate), 091 (Investigate crime), 092 (Investigate human rights)
10 - DEMAND
  • Ultimatum, requirement, insistence
  • Example: 100 (Demand), 101 (Demand material cooperation), 102 (Demand policy change)
11 - DISAPPROVE
  • Criticize, complain, condemn
  • Example: 110 (Disapprove), 111 (Criticize or denounce), 112 (Accuse)
12 - REJECT
  • Refuse, deny, reject requests
  • Example: 120 (Reject), 121 (Reject material cooperation), 122 (Reject request)
13 - THREATEN
  • Warn, issue threat, ultimatum
  • Example: 130 (Threaten), 131 (Threaten blockade), 138 (Threaten to use military force)
14 - PROTEST
  • Demonstrate, rally, strike
  • Example: 140 (Engage in political dissent), 141 (Demonstrate or rally), 142 (Conduct hunger strike)
15 - EXHIBIT FORCE POSTURE
  • Military exercises, mobilization, show of force
  • Example: 150 (Demonstrate military power), 151 (Increase military alert), 152 (Mobilize)
16 - REDUCE RELATIONS
  • Sanctions, embargo, cut ties
  • Example: 160 (Reduce relations), 161 (Reduce or stop aid), 162 (Impose embargo)
17 - COERCE
  • Force, intimidate, occupy
  • Example: 170 (Coerce), 171 (Seize possessions), 173 (Impose administrative sanctions)
18 - ASSAULT
  • Physical attack on persons
  • Example: 180 (Use unconventional violence), 181 (Abduct, kidnap), 182 (Physically assault)
19 - FIGHT
  • Armed combat, battle
  • Example: 190 (Use conventional military force), 191 (Impose blockade), 193 (Fight with small arms)
20 - USE UNCONVENTIONAL MASS VIOLENCE
  • WMD, terrorism, mass killing
  • Example: 200 (Use unconventional mass violence), 201 (Engage in mass expulsion), 203 (Engage in ethnic cleansing)
Resource URI: gdelt://codes/cameo-event
Example queries: Protests globally: 
SELECT day, actor1_name, action_geo_country_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND event_root_code = '14'
LIMIT 100
Military actions: 
SELECT day, actor1_name, actor2_name, event_code, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND event_root_code IN ('19', '20')
LIMIT 100
Use event_root_code for broad categories, event_code for specific actions.

​
Goldstein scale

Event intensity scale from -10 (most negative/conflictual) to +10 (most positive/cooperative).
Conflict spectrum:
  • -10 to -7: Violent conflict (fight, assault, mass violence)
  • -6 to -4: Non-violent conflict (threaten, reduce relations, coerce)
  • -3 to -1: Mild conflict (disapprove, reject, protest)
Neutral:
  • 0: Neutral actions (investigate, make statement)
Cooperation spectrum:
  • +1 to +2: Mild cooperation (consult, appeal positively)
  • +3 to +6: Material cooperation (cooperate economically/militarily, provide aid)
  • +7 to +10: Strong cooperation (host talks, sign major agreements, merge)
Example queries:Violent conflict:
SELECT day, actor1_name, actor2_name, event_code, goldstein_scale, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND goldstein_scale <= -7
ORDER BY goldstein_scale ASC
LIMIT 100
Strong cooperation:
SELECT day, actor1_name, actor2_name, event_code, goldstein_scale, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND goldstein_scale >= 7
ORDER BY goldstein_scale DESC
LIMIT 100
Resource URI: gdelt://codes/goldstein-scale
Goldstein scale provides numerical filtering for event intensity. Use with quad_class for conflict/cooperation categories.

​
Theme classification

​
GDELT theme taxonomy

Hierarchical theme taxonomy for topic-based article filtering.
ENV_ - Environmental themes*
  • ENV_CLIMATECHANGE - Climate change
  • ENV_DISASTER - Natural disasters
  • ENV_EMISSIONS - Emissions and pollution
  • ENV_DEFORESTATION - Deforestation
  • ENV_BIODIVERSITY - Biodiversity loss
  • ENV_WATER - Water issues
  • ENV_ENERGY - Energy topics
ECON_ - Economic themes*
  • ECON_INFLATION - Inflation
  • ECON_TRADE - Trade agreements/disputes
  • ECON_STOCKMARKET - Stock market
  • ECON_UNEMPLOYMENT - Unemployment
  • ECON_POVERTY - Poverty
  • ECON_DEBT - National/corporate debt
  • ECON_CURRENCY - Currency issues
CONFLICT_ - Conflict themes*
  • CONFLICT_MILITARY - Military conflict
  • CONFLICT_TERRORISM - Terrorism
  • CONFLICT_CYBER - Cyber warfare
  • CONFLICT_NUCLEAR - Nuclear weapons
  • CONFLICT_ARMS - Arms sales/control
GOV_ - Governance themes*
  • GOV_ELECTION - Elections
  • GOV_CORRUPTION - Corruption
  • GOV_POLICY - Policy changes
  • GOV_REGULATION - Regulatory issues
  • GOV_DIPLOMACY - Diplomatic relations
HEALTH_ - Health themes*
  • HEALTH_PANDEMIC - Pandemics/epidemics
  • HEALTH_POLICY - Health policy
  • HEALTH_HOSPITAL - Hospital/medical care
  • HEALTH_MENTAL - Mental health
  • HEALTH_DRUG - Drug issues
WB_ - World Bank indicators*
  • WB_* themes map to World Bank development indicators
UNGP_ - UN Global Pulse themes*
  • UNGP_* themes align with UN SDG goals
CRISISLEX_ - Crisis/disaster terms*
  • Coverage of casualties, evacuations, damage, relief
Resource URI: gdelt://codes/theme-gdelt-taxonomy
Example queries: Climate change articles: 
SELECT day, theme, document_identifier, tone
FROM gdelt_gkg_themes_extracted
WHERE day >= today() - INTERVAL 30 DAY
    AND theme LIKE 'ENV_CLIMATE%'
ORDER BY day DESC
LIMIT 500
Economic news: 
SELECT day, theme, COUNT(*) as article_count
FROM gdelt_gkg_themes_extracted
WHERE day >= today() - INTERVAL 7 DAY
    AND theme LIKE 'ECON_%'
GROUP BY day, theme
ORDER BY day DESC, article_count DESC
LIMIT 200
Use LIKE with wildcards for category-level filtering: theme LIKE 'ENV_%'

​
CrisisLex themes

Specialized crisis and disaster terminology for emergency event tracking.
Casualties & Injuries:
  • Fatalities, deaths, casualties
  • Injured, wounded
  • Missing persons
Evacuations & Displacement:
  • Evacuations, refugees
  • Displaced persons
  • Shelter needs
Infrastructure Damage:
  • Building collapses
  • Infrastructure damage
  • Power outages
Relief & Aid:
  • Humanitarian aid
  • Emergency response
  • Rescue operations
  • Medical assistance
Emergency Response:
  • First responders
  • Search and rescue
  • Emergency declarations
Resource URI: gdelt://codes/theme-crisislex
Example query: Crisis events: 
SELECT day, theme, document_identifier, tone
FROM gdelt_gkg_themes_extracted
WHERE day >= today() - INTERVAL 7 DAY
    AND theme LIKE 'CRISISLEX_%'
ORDER BY day DESC
LIMIT 200

​
Best practices

Start broad, then narrow - Begin with root codes or top-level themes, then add specificity
Combine complementary codes - Use actor types + event codes + locations for precision
Understand sparsity - Ethnic and religion codes are sparse; use as secondary filters
Don’t mix WHO and WHERE codes - CAMEO (ISO-3) for actors, FIPS (2-char) for locations

​
Quick reference

Code TypeUse ForColumn NamesFormat
CAMEO CountryActor filtering (WHO)actor*_country_codeISO-3 (USA, CHN)
FIPS CountryLocation filtering (WHERE)*_geo_country_codeFIPS 2-char (US, CH)
CAMEO TypeActor classificationactor_type_code3-char (GOV, MIL)
Known GroupsOrganizationsactor*_known_group_codeNames (NATO, UN)
Event CodesEvent classificationevent_*_code2-4 digits (14, 182)
GoldsteinEvent intensitygoldstein_scale-10 to +10
ThemesTopic filteringthemeHierarchical (ENV_*)

​
Next steps

Table Schemas

Learn about the 9 GDELT tables where these codes are used

Prepare Query

Get schemas and codes bundled for query building

Get Resource

Fetch individual code references on demand

System Prompt

Core system prompt with code usage guidance