GDELT Cloud Documentation - Real-time Global Events API

Overview

The get_resource tool fetches specific GDELT table schemas or code references on demand. It’s designed for answering user questions about tables, columns, or valid codes without needing to call prepare_gdelt_query.

This tool provides quick access to individual resources. For building queries, use prepare_gdelt_query which bundles multiple resources together.

When to use

Use get_resource when:

A user asks “What columns are in the events table?”
A user asks “What does event code 14 mean?”
A user asks “Show me all country codes”
You need to reference a specific schema or code catalog
Answering documentation or reference questions

Don’t use for query building - Use prepare_gdelt_query instead, which provides targeted schemas and codes based on your query needs.

Parameters

resource_name

string

required

Resource to fetch. Choose from 19 available resources: 9 table schemas + 10 code references.Table schemas:

gdelt_events - WHO-WHAT-WHERE-WHEN structured events
gdelt_mentions - Event-to-article bridge table
mv_event_mention_stats - Pre-aggregated coverage metrics
gdelt_gkg_themes_extracted - Topic/theme filtering
gdelt_gkg_persons_extracted - Person mentions
gdelt_gkg_organizations_extracted - Organization mentions
gdelt_gkg_locations_extracted - Location mentions with coordinates
gdelt_persons_master - Historical person tracking (all-time)
gdelt_organizations_master - Historical org tracking (all-time)

Code references:

cameo_country_codes - ISO-3 country codes for actor filtering (USA, CHN, GBR)
fips_country_codes - FIPS 2-char codes for location filtering (US, CH, UK)
cameo_type_codes - Actor types (GOV, MIL, COP, EDU, etc.)
cameo_known_groups - International organizations (NATO, UN, EU, etc.)
cameo_ethnic_codes - Ethnic group classifications
cameo_religion_codes - Religious affiliations
cameo_event_codes - CAMEO event taxonomy (01-20 root codes)
goldstein_scale - Event intensity mapping (-10 to +10)
theme_gdelt_taxonomy - GDELT theme codes (ENV_, ECON_, etc.)
theme_crisislex - Crisis/disaster terms

Response

Returns complete schema or code reference as a formatted string with: For table schemas:

Column names and data types
Column descriptions
Sample values
Query patterns and tips

For code references:

Complete code lists
Code descriptions
Usage context
Filtering examples

Resources are returned in full without truncation, making them ideal for comprehensive reference.

Usage examples

# Get events table schema
get_resource(resource_name="gdelt_events")

# Get country codes for filtering
get_resource(resource_name="cameo_country_codes")

# Get event codes taxonomy
get_resource(resource_name="cameo_event_codes")

# Get Goldstein scale mapping
get_resource(resource_name="goldstein_scale")

Common use cases

Answering schema questions

User asks: “What columns are available in the events table?”

get_resource(resource_name="gdelt_events")

Returns complete column list with types and descriptions.

Explaining codes

User asks: “What event codes are available for filtering?”

get_resource(resource_name="cameo_event_codes")

Returns full CAMEO event taxonomy with code numbers and meanings.

Understanding metrics

User asks: “How does the Goldstein scale work?”

get_resource(resource_name="goldstein_scale")

Returns Goldstein scale mapping with natural language translations.

Exploring themes

User asks: “What themes can I filter by?”

get_resource(resource_name="theme_gdelt_taxonomy")

Returns complete GDELT theme taxonomy (ENV_, ECON_, CONFLICT_*, etc.).

Resource catalog

Table Schemas (9 resources)

gdelt_events

Core events table with WHO-WHAT-WHERE-WHEN structure. Includes actors, event codes, locations, dates, and Goldstein scale.Key columns: event_id, day, actor1_name, actor2_name, event_code, goldstein_scale, source_urlSpeed: Very fast (< 1s for recent queries)

gdelt_mentions

Bridge table connecting events to GKG articles. Tracks which articles mention which events.Key columns: event_id, day, mention_identifier, mention_time_date, confidenceUse for: Coverage analysis, finding articles about specific events

mv_event_mention_stats

Pre-aggregated materialized view with coverage metrics per event.Key columns: event_id, day, mention_count, source_count, avg_toneSpeed: Fastest (< 0.5s), use for trending/viral event detection

gdelt_gkg_themes_extracted

Theme codes extracted from GKG articles for topic filtering.Key columns: day, document_identifier, theme, toneUse for: Topic-based article filtering (ENV_, ECON_, HEALTH_*, etc.)

gdelt_gkg_persons_extracted

Person names mentioned in articles.Key columns: day, document_identifier, person_name, char_offsetUse for: Tracking mentions of specific individuals

gdelt_gkg_organizations_extracted

Organization names mentioned in articles.Key columns: day, document_identifier, organization_name, char_offsetUse for: Tracking mentions of companies, institutions, NGOs

gdelt_gkg_locations_extracted

Geographic locations mentioned in articles with coordinates.Key columns: day, document_identifier, location_name, country_code, latitude, longitudeUse for: Geographic analysis, mapping article mentions

gdelt_persons_master

Historical person tracking across all time (no 30-day limit).Key columns: person_name, first_seen, last_seen, mention_countUse for: Long-term person tracking, historical analysis

gdelt_organizations_master

Historical organization tracking across all time (no 30-day limit).Key columns: organization_name, first_seen, last_seen, mention_countUse for: Long-term org tracking, institutional analysis

Code References (10 resources)

cameo_country_codes

ISO-3 country codes for filtering WHO (actors) in events.Format: USA, CHN, GBR, FRA, RUS, etc.Use with: actor1_country_code, actor2_country_code in gdelt_events

fips_country_codes

FIPS 2-character country codes for filtering WHERE (locations).Format: US, CH, UK, FR, RS, etc.Use with: *_geo_country_code in gdelt_events, country_code in gdelt_gkg_locations_extracted

cameo_type_codes

Actor classification codes for organizational types.Examples: GOV, MIL, COP, EDU, MED, BUS, REL, etc.Use with: actor_type1_code, actor_type2_code, actor*_type3_code

cameo_known_groups

International organization and known group codes.Examples: NATO, UN, EU, ASEAN, BRICS, etc.Use with: actor*_known_group_code (high precision, low recall)

cameo_ethnic_codes

Ethnic group classification codes.Note: Sparse field, use as secondary filterUse with: actor*_ethnic_code

cameo_religion_codes

Religious affiliation codes.Note: Sparse field, use as secondary filterUse with: actor_religion1_code, actor_religion2_code

cameo_event_codes

Complete CAMEO event taxonomy (01-20 root codes).Root codes:

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
14: Protest
15: Exhibit force posture
16: Reduce relations
17: Coerce
18: Assault
19: Fight
20: Use unconventional mass violence

Use with: event_code, event_base_code, event_root_code

goldstein_scale

Event intensity scale from -10 (most negative) to +10 (most positive).Natural language mapping:

-10 to -7: Violent conflict
-6 to -4: Non-violent conflict
-3 to -1: Mild conflict
0: Neutral
+1 to +2: Mild cooperation
+3 to +6: Material cooperation
+7 to +10: Strong cooperation

Use with: goldstein_scale, quad_class in gdelt_events

theme_gdelt_taxonomy

GDELT Global Knowledge Graph theme taxonomy.Categories:

ENV_* - Environment (ENV_CLIMATECHANGE, ENV_DISASTER, etc.)
ECON_* - Economy (ECON_INFLATION, ECON_TRADE, etc.)
CONFLICT_* - Conflict (CONFLICT_MILITARY, CONFLICT_TERRORISM, etc.)
GOV_* - Governance (GOV_ELECTION, GOV_CORRUPTION, etc.)
HEALTH_* - Health (HEALTH_PANDEMIC, HEALTH_POLICY, etc.)
WB_* - World Bank indicators
UNGP_* - UN Global Pulse themes

Use with: theme in gdelt_gkg_themes_extracted

theme_crisislex

CrisisLex terms for crisis and disaster event filtering.Coverage:

Casualties and injuries
Evacuations and displacement
Infrastructure damage
Relief and aid efforts
Emergency response

Use with: theme column (CRISISLEX_* patterns) in gdelt_gkg_themes_extracted

Resource URIs

Resources are also available directly via MCP resource URIs: Table schemas:

gdelt://schema/events
gdelt://schema/mentions
gdelt://schema/event-mention-stats
gdelt://schema/themes-extracted
gdelt://schema/persons-extracted
gdelt://schema/organizations-extracted
gdelt://schema/locations-extracted
gdelt://schema/persons-master
gdelt://schema/organizations-master

Code references:

gdelt://codes/cameo-country
gdelt://codes/fips-country
gdelt://codes/cameo-type
gdelt://codes/cameo-known-groups
gdelt://codes/cameo-ethnic
gdelt://codes/cameo-religion
gdelt://codes/cameo-event
gdelt://codes/goldstein-scale
gdelt://codes/theme-gdelt-taxonomy
gdelt://codes/theme-crisislex

Best practices

For query building, use prepare_gdelt_query - It intelligently bundles the schemas and codes you need based on your table selection.

Use get_resource for reference - Perfect for answering questions or looking up specific codes without the overhead of query preparation.

Resources are comprehensive - Every resource returns complete information without truncation or pagination.

Comparison with prepare_gdelt_query

Feature	get_resource	prepare_gdelt_query
Purpose	Reference lookup	Query preparation
Returns	Single resource	Multiple resources + guidance
Use case	Answering questions	Building queries
Performance	Fast, targeted	Fast, bundled
JOIN guidance	No	Yes
Code filtering	No	Yes (via flags)

Rule of thumb: Use get_resource for documentation, use prepare_gdelt_query for query workflows.

Example workflows

Documentation assistant

User: “What columns are in the themes table?”

get_resource(resource_name="gdelt_gkg_themes_extracted")

Response includes all columns with descriptions and query examples.

Code lookup

User: “What’s the event code for protests?”

get_resource(resource_name="cameo_event_codes")

Find code 14 in the returned taxonomy.

Scale interpretation

User: “How negative is a Goldstein scale of -8?”

get_resource(resource_name="goldstein_scale")

Response shows -8 maps to “violent conflict” category.

Theme exploration

User: “Can I filter by environmental themes?”

get_resource(resource_name="theme_gdelt_taxonomy")

Response shows all ENV_* theme codes available.

Error handling

Invalid resource name

Error: Resource ‘xyz’ not foundSolution: Use only the 19 valid resource names listed in the parameters section. Check spelling carefully.Common mistakes:

events → correct is gdelt_events
country_codes → specify either cameo_country_codes or fips_country_codes
themes → correct is gdelt_gkg_themes_extracted (for schema) or theme_gdelt_taxonomy (for codes)

Authentication error

Error: “Authentication required”Solution: Ensure your bearer token is properly configured. See authentication guide.

Next steps

Table Schemas

Detailed overview of all 9 GDELT tables

Code References

Complete guide to all 10 code catalogs

Prepare Query

Use for query building workflows

System Prompt

Core GDELT system prompt with tables and workflow

Overview

Tools

Resources

Prompts

Integrations

​Overview

​When to use

​Parameters

​Response

​Usage examples

​Common use cases

​Answering schema questions

​Explaining codes

​Understanding metrics

​Exploring themes

​Resource catalog

​gdelt_events

​gdelt_mentions

​mv_event_mention_stats

​gdelt_gkg_themes_extracted

​gdelt_gkg_persons_extracted

​gdelt_gkg_organizations_extracted

​gdelt_gkg_locations_extracted

​gdelt_persons_master

​gdelt_organizations_master

​cameo_country_codes

​fips_country_codes

​cameo_type_codes

​cameo_known_groups

​cameo_ethnic_codes

​cameo_religion_codes

​cameo_event_codes

​goldstein_scale

​theme_gdelt_taxonomy

​theme_crisislex

​Resource URIs

​Best practices

​Comparison with prepare_gdelt_query

​Example workflows

​Documentation assistant

​Code lookup

​Scale interpretation

​Theme exploration

​Error handling

​Next steps

Table Schemas

Code References

Prepare Query

System Prompt

Overview

When to use

Parameters

Response

Usage examples

Common use cases

Answering schema questions

Explaining codes

Understanding metrics

Exploring themes

Resource catalog

gdelt_events

gdelt_mentions

mv_event_mention_stats

gdelt_gkg_themes_extracted

gdelt_gkg_persons_extracted

gdelt_gkg_organizations_extracted

gdelt_gkg_locations_extracted

gdelt_persons_master

gdelt_organizations_master

cameo_country_codes

fips_country_codes

cameo_type_codes

cameo_known_groups

cameo_ethnic_codes

cameo_religion_codes

cameo_event_codes

goldstein_scale

theme_gdelt_taxonomy

theme_crisislex

Resource URIs

Best practices

Comparison with prepare_gdelt_query

Example workflows

Documentation assistant

Code lookup

Scale interpretation

Theme exploration

Error handling

Next steps