curl --request GET \
--url https://gdeltcloud.com/api/v2/countries \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/countries"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/countries', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": []
}Read country activity
Country publication aggregates and hourly evidence from the shared activity journal. Additions, updates and linked entities are separate metrics. Facility additions count published registry records (units), not newly built or deduplicated physical sites; country context inventories expose site and unit totals separately. All matching countries are included; this map is independent of evidence pagination. Source collection gaps remain explicit: unknown or withheld source counts are null in both country and hourly rows. Events/Stories remain unknown on absent rows until source-wide coverage evidence exists; a serving replay watermark alone does not qualify a zero. Positive committed counts remain visible. meta.coverage.window_complete reports whether every selected source has evidence covering the selected window; hourly_window_complete covers the entire timeline day. Actor-direction edges use Event occurrence dates, separately from publication activity. meta.edges_coverage exposes availability, status and oldest serving snapshot as_of; unavailable snapshots do not imply zero relationships.
curl --request GET \
--url https://gdeltcloud.com/api/v2/countries \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/countries"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/countries', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": []
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Clock for date/hour filters and ordering: published preserves the serving/reference publication time; recorded uses the durable journal commit time and includes late publications when they become available. Omission retains published compatibility. Choose recorded explicitly for ongoing activity Monitors; source dates remain unchanged. Full value list: https://docs.gdeltcloud.com/reference/enums#activity-time-basis
published, recorded First UTC date in the selected time_basis. Defaults to today; future dates are rejected. Neither clock is Event occurrence time. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Last UTC date in the selected time_basis, inclusive. Defaults to date_start and cannot be later than the current UTC day. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
UTC hour selecting a publication bucket on one UTC date. Rejects hours that have not started. The current hour is allowed and describes publications so far; omit for the whole selected day. Requires date_start and date_end to be equal when both are sent. An hour selects one UTC date.
0 <= x <= 23Known country attribution. Evidence distinguishes location, actor origin, reporting and source association. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#country
publication retains the activity journal clock. reporting uses distinct served Events by occurrence date and location country (country_match=location), and Stories by reporting date under every authoritative country association (the Stories summary country_attribution=all mode). Country buckets may overlap for Stories; totals are computed independently. With basis=reporting: cannot be combined with hour. Reporting has day precision; select publication for hourly changes. Full value list: https://docs.gdeltcloud.com/reference/enums#country_basis
publication, reporting Include Event metric maxima with tied-country evidence, five AI-coded metric averages with scored Event counts, and per-country readings/linked identity counts. totals.entities_spotted counts distinct served identity/id-space pairs across the entire scoped Event set, never summed over countries; null when unavailable or not requested. Occurrence-date and location scope. Averages weight each finite scored canonical Event equally, independently of directory pagination. Unrestricted world averages and linked-identity totals include unlocated/global Events; geographic filters use location. Goldstein remains a signed maximum only. No scored observations gives null/count 0; unavailable context remains null. With include_event_metrics=true: requires basis=reporting.
Include dated macro rollups for the selected geography, with same-period coverage and aggregation methods. Requires intelligence entitlement.
Include every registered country, even those without observed activity. When omitted, returns the activity view rather than the paginated directory.
Country directory name or ISO code search. Requires directory=true. Omit directory-only parameters for the complete activity map.
Registered geographic region whose member countries narrow the country activity or directory view. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#region
Middle East, Northern Africa, Western Africa, Eastern Africa, Middle Africa, Southern Africa, Eastern Europe, South Asia, Southeast Asia, East Asia, Central Asia, Northern America, Central America, Caribbean Registered continent whose member countries narrow the country activity or directory view. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Full value list: https://docs.gdeltcloud.com/reference/enums#continent
Africa, Asia, Europe, North America, South America, Oceania Directory order: most recently seen in reporting/publication activity (default), name alphabetically, events or stories descending with stable name ties. Requires directory=true. Omit directory-only parameters for the complete activity map. Full value list: https://docs.gdeltcloud.com/reference/enums#country_directory_sort
recent, name, events, stories Number of countries per directory page. Requires directory=true. Omit directory-only parameters for the complete activity map. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
1 <= x <= 250Number of directory countries to skip. Requires directory=true. Omit directory-only parameters for the complete activity map.
x >= 0Response
Success
true Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Independently counted activity totals. On reporting basis with include_event_metrics=true, entities_spotted is the distinct served identity/id-space count across the entire scoped Event population, including unlocated/global Events at world scope; null when unavailable or not requested. Never sum overlapping country entity counts.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Maximum signed Event metrics by occurrence date, with evidence from every tied country.
Show child attributes
Show child attributes
Five AI-coded metric means weighted by scored Event observations, never country means or maxima. Independent of directory pagination. World scope includes unlocated Events; geographic filters use Event location. Null when context is unavailable or not requested.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes