Search Facilities
Unified physical-asset directory — GEM energy and heavy-industry sites, WPI ports and AI data centers, deduped to one facility per real-world site.
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.
Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Rows per page. Default 25, max 100. 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 <= 100Opaque pagination cursor taken from the previous response's pagination.next_cursor. 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.
Case-insensitive substring match over name. This is NOT semantic search — nothing is embedded, and a conceptually related term that does not appear literally will not match. Results are ordered by facility name (A–Z), not by relevance, so a query matching more rows than limit returns an arbitrary slice. 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.
Facility type (21 values). 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 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 Source silo the facility was projected from. 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 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
Africa, Asia, Middle East, Northern Africa, Western Africa, Eastern Africa, Middle Africa, Southern Africa, Europe, Eastern Europe, South Asia, Southeast Asia, East Asia, Central Asia, North America, Central America, Caribbean, South America, Oceania 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 Owner filter. An e_ spine id matches the resolved owner exactly; a name falls back to a fuzzy match on owner 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 · 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.
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.