curl --request GET \
--url https://gdeltcloud.com/api/v2/geo/admin1 \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/geo/admin1"
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/geo/admin1', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"country": "France",
"admin1": [
"Auvergne-Rhone-Alpes",
"Bretagne",
"Ile-de-France",
"Normandie",
"Provence-Alpes-Cote d Azur"
]
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}List Admin1 Values
Discover the admin1 (state / province / oblast) values available for one country, measured over a trailing window of the settled Events table and canonicalised to exactly the tokens the admin1 filter on /api/v2/events and /api/v2/stories accepts — so discover→filter round-trips without guessing spellings. Each region appears ONCE, under whichever spelling carries the most events, with that count attached; a trailing administrative suffix (“Donetsk” vs “Donetsk Oblast”) is folded on both sides by the filter, so either spelling returns the same events. This endpoint is intentionally country-scoped and does not return the full admin1 catalog.
curl --request GET \
--url https://gdeltcloud.com/api/v2/geo/admin1 \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/geo/admin1"
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/geo/admin1', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"country": "France",
"admin1": [
"Auvergne-Rhone-Alpes",
"Bretagne",
"Ile-de-France",
"Normandie",
"Provence-Alpes-Cote d Azur"
]
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Country to enumerate admin1 (state/province) values for — required. Accepts a country name (France), ISO-2 (FR), or ISO-3 (FRA); an unresolvable or missing value returns 400 INVALID_COUNTRY. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Trailing window in days the region counts are measured over, ending today unless date moves the anchor. Both 7 and 7d are accepted. The window actually used is echoed as window_days and in applied_filters. Also accepts: window. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Anchor date for the window. Alone it selects that single day; combined with days it ends the trailing span on that date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
First day of an explicit window. May not be combined with days/window. Also accepts: start_date. 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 day of an explicit window. May not be combined with days/window. Also accepts: end_date. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Response
Country-scoped admin1 values
true gdelt_cloud.serving_events, adm1_catalog, none Show child attributes
Show child attributes
Show child attributes
Show child attributes