curl --request GET \
--url https://gdeltcloud.com/api/v2/facilities \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/facilities"
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/facilities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": [
{
"facility_id": "s_8dead1adbc3b3684",
"canonical_site_id": "s_8dead1adbc3b3684",
"granularity": "site",
"unit_id": null,
"unit_count": 5,
"unit_ids": [
"f_62714966cc4b283a"
],
"unit_statuses": [
{
"facility_id": "f_62714966cc4b283a",
"status_source": "operating",
"status": "operating"
}
],
"status_breakdown": [
{
"status": "operating",
"unit_count": 5
}
],
"name": "Zaporizhzhia Ferroalloys Plant",
"facility_type": "steel_plant",
"facility_class": "heavy_industry",
"source_silo": "gem",
"country_iso3": "UKR",
"lat": 47.86,
"lon": 35.1,
"status": "operating",
"status_source": "operating",
"status_sources": [
"operating"
],
"capacity_mw": null,
"owners": [
{
"entity_id": "e_e3369180240c3a9e",
"name": "Dniprospetsstal Plant PJSC"
}
],
"url": "https://gdeltcloud.com/facilities/zaporizhzhia-ferroalloys-plant-s_8dead1adbc3b3684",
"attributes": {},
"detail_url": "/api/v2/facilities/s_8dead1adbc3b3684",
"owner_portfolio_url": "/api/v2/facilities?owner_entity_id=e_e3369180240c3a9e"
}
],
"meta": {
"granularity": "site",
"count_unit": "canonical_sites"
},
"pagination": {
"limit": 1,
"offset": 0,
"returned": 1,
"has_more": false,
"next_cursor": null
},
"applied_filters": {
"granularity": "site",
"limit": 1
}
}{
"success": false,
"error": "Invalid type 'power_plant'. Accepted: coal_plant, oil_gas_plant, nuclear_plant, …, port, data_center",
"code": "INVALID_ENUM"
}{
"error": "API key required. Include: Authorization: Bearer gdelt_sk_...",
"code": "MISSING_API_KEY"
}{
"success": false,
"error": "Your plan does not include the Facilities data source.",
"code": "PLAN_REQUIRED"
}{
"success": false,
"error": "Rate limit or quota exceeded.",
"code": "RATE_LIMITED"
}{
"success": false,
"error": "Failed to fetch facilities.",
"code": "INTERNAL_ERROR"
}Search Facilities
Physical-asset directory combining GEM energy and heavy industry, ports, Epoch and ComputeAtlas data centers, USGS mineral facilities, Climate TRACE and EEA factories. Independently reviewed cross-source identities share a canonical site; source observations, units and unresolved ownership remain explicit. Each card returns a public GDELT Cloud facility url for citations, separate from REST detail_url and dataset attribution.
Parameters this endpoint deliberately rejects (1)
Parameters this endpoint deliberately rejects (1)
These return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.
admin1→ 400 UNSUPPORTED_FILTER. Facilities carry no sub-national admin1 column. Filter by country / region / continent / bbox / near instead. Use instead:country,region,continent,bbox,near.
curl --request GET \
--url https://gdeltcloud.com/api/v2/facilities \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/facilities"
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/facilities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": [
{
"facility_id": "s_8dead1adbc3b3684",
"canonical_site_id": "s_8dead1adbc3b3684",
"granularity": "site",
"unit_id": null,
"unit_count": 5,
"unit_ids": [
"f_62714966cc4b283a"
],
"unit_statuses": [
{
"facility_id": "f_62714966cc4b283a",
"status_source": "operating",
"status": "operating"
}
],
"status_breakdown": [
{
"status": "operating",
"unit_count": 5
}
],
"name": "Zaporizhzhia Ferroalloys Plant",
"facility_type": "steel_plant",
"facility_class": "heavy_industry",
"source_silo": "gem",
"country_iso3": "UKR",
"lat": 47.86,
"lon": 35.1,
"status": "operating",
"status_source": "operating",
"status_sources": [
"operating"
],
"capacity_mw": null,
"owners": [
{
"entity_id": "e_e3369180240c3a9e",
"name": "Dniprospetsstal Plant PJSC"
}
],
"url": "https://gdeltcloud.com/facilities/zaporizhzhia-ferroalloys-plant-s_8dead1adbc3b3684",
"attributes": {},
"detail_url": "/api/v2/facilities/s_8dead1adbc3b3684",
"owner_portfolio_url": "/api/v2/facilities?owner_entity_id=e_e3369180240c3a9e"
}
],
"meta": {
"granularity": "site",
"count_unit": "canonical_sites"
},
"pagination": {
"limit": 1,
"offset": 0,
"returned": 1,
"has_more": false,
"next_cursor": null
},
"applied_filters": {
"granularity": "site",
"limit": 1
}
}{
"success": false,
"error": "Invalid type 'power_plant'. Accepted: coal_plant, oil_gas_plant, nuclear_plant, …, port, data_center",
"code": "INVALID_ENUM"
}{
"error": "API key required. Include: Authorization: Bearer gdelt_sk_...",
"code": "MISSING_API_KEY"
}{
"success": false,
"error": "Your plan does not include the Facilities data source.",
"code": "PLAN_REQUIRED"
}{
"success": false,
"error": "Rate limit or quota exceeded.",
"code": "RATE_LIMITED"
}{
"success": false,
"error": "Failed to fetch facilities.",
"code": "INTERNAL_ERROR"
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Number of records to return on this page; use the returned continuation to request the next page. 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 <= 100Continuation from pagination.next_cursor in the previous response. Keep the other filters unchanged; null means no next page. Also accepts: offset. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
site (default) returns one canonical physical site; unit exposes source registry units. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Facility name. Default lexical mode keeps case-insensitive substring matching. Opt-in search_mode=fuzzy suggests names with matching prefixes or small spelling errors; every query token must match a name token. These are selectable candidates, not resolved site identity. No embedding or inference runs. Also accepts: search. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
lexical (default) preserves substring search. fuzzy requires 2–200 characters and 1–12 name tokens; small typos and token prefixes are supported. Use sort=relevance to put literal matches before fuzzy suggestions. Other category/geography filters stay exact. Full value list: https://docs.gdeltcloud.com/reference/enums#facility_name_search_mode
lexical, fuzzy Facility type. Comma-separate for OR. 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#facility_type
coal_plant, oil_gas_plant, nuclear_plant, geothermal_plant, bioenergy_plant, hydropower_plant, solar_farm, wind_farm, coal_mine, oil_gas_field, iron_ore_mine, coal_terminal, lng_terminal, gas_pipeline, oil_pipeline, lng_carrier, port, steel_plant, cement_plant, chemical_plant, data_center, mineral_mine, concentrator, smelter, mineral_refinery, smelter_refinery, mineral_processing_plant, recycling_plant, manufacturing_factory Broad facility class; expanded to its member types. 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#facility_class
power, extraction, transport_logistics, ports, heavy_industry, digital_infrastructure, mineral_processing, manufacturing Contributing source membership; keeps all observations for each matching canonical site. 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#facility_source_silo
gem, maritime_ports, epoch, usgs_domestic, usgs_myb, climate_trace, compute_atlas, eea_industrial Observed current-directory commodity values are suggestions, not a closed vocabulary; comma-separate for OR. New values are accepted. A mine and a refinery remain separate assets. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Observed vocabulary, measured 2026-10-02 (116 distinct values). Values outside it are accepted, not rejected. Discover current values: GET /api/v2/meta/enums (facility_commodity) or inspect facility card commodities. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#facility_commodity
Match a resolved entity named in a source participant record. This is separate from entity and owner filters; a role assertion does not establish ownership. 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#entity_handle
Exact source-reported participant role. Open vocabulary (for example operator or tenant); this does not establish ownership.
Lifecycle status. Matched case-insensitively — the corpus carries both operating and Operating — and GEM's "- inferred N y" variants fold into their base state. This is an OBSERVED vocabulary measured from the directory, not a closed list. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply. Observed vocabulary, measured 2026-08-10 (32 distinct values). Values outside it are accepted, not rejected. Discover current values: GET /api/v2/facilities?limit=1 (see applied_filters) or /api/v2/meta/enums. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#facility_status
Country filter (ISO-3). region and continent expand to their member countries. A facility matches on either its primary or secondary country. Matched case-insensitively. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Region; expanded to member countries. 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 Continent; expanded to member countries. 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 Resolved owner filter using the shared entity resolver for names and supported identifiers. owner and owner_entity_id preserve this identity meaning. Use owner_search explicitly for fuzzy matching of owner names, including unresolved names. Also accepts: owner_entity_id, owner_search, owner. 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#entity_handle
Minimum capacity in MW. Capacity units differ per tracker — see the tracker reference. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
x >= 0Maximum capacity in MW. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
x >= 0Restrict to facilities that do (or do not) carry coordinates. 99.15% of the directory does; the residual are GEM linear/areal assets — pipelines and fields — which are geometry, not a point. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
true restricts to facilities with a SPINE-RESOLVED owner (owners[].entity_id non-null). A facility can carry an unresolved owner NAME and still be excluded — that is the documented meaning of "owner" here, and it is the resolved id that makes owner-bridge fusion and entity= chaining possible. Owner coverage is 47.1% overall: heavy industry 99.9%, AI data centers 85%, GEM power 43%, ports 0% (WPI publishes no ownership layer). Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Ordering: name · capacity_desc · capacity_asc · recent (directory updates) · country · relevance (requires q; exact name, literal substring, then token distance) · news_activity. News activity ranks the entire filtered directory by direct-owner Event count first, then the distinct owner/nearby Event union over seven recent days, matched to explicit owner identities on Event cards or within 25 km; overlaps count once. Parent rollups are excluded. Counts and exact served dates are disclosed; nearby reporting does not establish a site incident. 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#facility_sort
name, capacity_desc, capacity_asc, recent, country, news_activity, relevance Bounding box lat_min,lon_min,lat_max,lon_max. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
Point proximity lat,lon,radius_km, refined by true great-circle distance. Note this is the three-part grammar — /api/v2/events takes near=lat,lon with a separate radius_km. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.