> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Facilities
> The unified physical-asset directory — GEM energy assets, World Port Index ports, and Epoch AI data centers on one keyed surface, each resolved to its owner entities on the spine.
The Facilities API is a **single directory of real-world physical assets** — power
plants, mines, pipelines, LNG terminals, ports, and AI data centers — projected from
three source silos and unified on a stable `facility_id`:
| Silo (`source`) | What it contributes | Geography | Owners |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ------------------------ |
| `gem` | Global Energy Monitor — energy assets (plants, mines, terminals, pipelines) **plus heavy industry** (steel / cement / chemical / iron-ore) | ✅ lat/lon (pipelines excepted) | ✅ spine entity\_ids |
| `maritime_ports` | World Port Index ports | ✅ lat/lon | — (ports carry no owner) |
| `epoch` | Epoch AI data centers | — (geo-null in v1) | ✅ spine entity\_ids |
Every facility carries its owners as spine `entity_id`s, so a plant / terminal / field /
data center joins the live Events / Stories / Entities graph — from a facility you can pivot
to its operator's entity page, or from an entity to every facility it owns. This is the join
surface the physical-risk, asset-adjacent-threat, and supply-chain-disruption workflows are
built on ("what exists near this event, and who operates it").
The Facilities endpoints are **plan-gated** — they require the `can_use_facilities`
entitlement, included on the **Analyst plan and up**. Plans below Analyst receive a clean
`403 PLAN_REQUIRED`.
Directory-only in v1 (list + single-facility detail + owner→portfolio). The facility × event
fusion (`facilities/{id}/events`) is a separate stream. Facilities are rebuilt whenever a
source silo reloads; owners are resolved into the same entity spine used across the rest of
the API. GEM data is [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/) (Global Energy
Monitor); ports are the public NGA World Port Index; data centers are Epoch AI (CC-BY 4.0).
## Taxonomy — the type & class enums
Facilities are filtered by a **leaf `type`** or a **coarse `class`**. Both are validated
enums: an unknown value returns `400 INVALID_ENUM` listing the accepted set.
**`class`** (coarse grouping):
| Class | Leaf types |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `power` | `coal_plant`, `oil_gas_plant`, `nuclear_plant`, `geothermal_plant`, `bioenergy_plant`, `hydropower_plant`, `solar_farm`, `wind_farm` |
| `extraction` | `coal_mine`, `oil_gas_field`, `iron_ore_mine` |
| `transport_logistics` | `coal_terminal`, `lng_terminal`, `gas_pipeline`, `oil_pipeline`, `lng_carrier` |
| `ports` | `port` |
| `heavy_industry` | `steel_plant`, `cement_plant`, `chemical_plant` |
| `digital_infrastructure` | `data_center` |
Pass one or more leaf types as a comma-separated `type` list, or a single `class` to grab
every leaf type in that class.
## Endpoints
Both endpoints require `Authorization: Bearer gdelt_sk_...` and return a JSON body with
`success: true`. Non-entitled plans receive `403 PLAN_REQUIRED`.
### Search Facilities
`GET /api/v2/facilities` — search the directory, returning facility cards (identity,
type/class, source silo, country + coordinates, owners with spine entity\_ids, status,
capacity, and follow-on URLs). Paginated with `limit` (max 100) + `cursor`.
| Param | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` | Case-insensitive substring match on the facility name. |
| `type` | One or more leaf facility types (comma-separated enum — see taxonomy above). |
| `class` | One coarse class — grabs every leaf type in it (validated enum — see taxonomy above): `power`, `extraction`, `transport_logistics`, `ports`, `heavy_industry`, `digital_infrastructure`. |
| `source` | Restrict to source silos: `gem`, `maritime_ports`, `epoch` (comma-separated). |
| `country` | Country name or ISO-2/ISO-3 code(s), comma-separated. Matches primary or secondary country. |
| `region` | One plain-English region (e.g. `Middle East`), expanded to its country list. |
| `continent` | One plain-English continent (`Asia`, `Europe`, `Africa`, `North America`, `South America`, `Oceania`). |
| `entity` | Canonical owner selector (the same `entity` works across facilities / energy / gov). Pass a spine `e_…` id for an EXACT owner match, or any name for a case-insensitive fuzzy owner-name match. Preferred over the legacy `owner_entity_id` / `owner_search` below. |
| `owner_entity_id` | Legacy — prefer `entity`. Spine entity\_id (`e_...`) — facilities this entity owns. [Resolve a name to an entity id](/api-reference/concepts#finding-an-entity-when-you-dont-know-the-exact-name) first. |
| `owner_search` | Legacy — prefer `entity`. Case-insensitive substring match on the owner name (no id needed). |
| `status` | Operating-status value(s), comma-separated, case-insensitive (`operating`, `construction`, `proposed`, `retired`, …). |
| `capacity_mw_min` / `capacity_mw_max` | Capacity bounds in MW (power facilities + data centers only). |
| `has_geo` | `true` → only facilities with coordinates (excludes geo-null data centers). |
| `has_owner` | `true` → only facilities with a resolved spine owner (excludes ports). |
| `bbox` | Geographic viewport `lat_min,lon_min,lat_max,lon_max`. |
| `near` | Proximity `lat,lon,radius_km` — facilities within the radius of a point. |
| `sort` | `name` (default), `capacity_desc`, `capacity_asc`, `recent`, `country`. |
| `limit` | Cards per page (default 25, max 100). |
| `cursor` | Pagination cursor from `pagination.next_cursor`. |
```bash theme={null}
# LNG terminals near the US Gulf Coast (physical-risk screen)
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
"https://gdeltcloud.com/api/v2/facilities?type=lng_terminal&near=29.3,-94.8,400&limit=25"
# Every facility a spine entity operates (owner → portfolio)
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
"https://gdeltcloud.com/api/v2/facilities?owner_entity_id=e_a4db9cd53edee666&limit=50"
# AI data centers (Epoch silo)
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
"https://gdeltcloud.com/api/v2/facilities?type=data_center&limit=25"
```
### Get Facility
`GET /api/v2/facilities/{facility_id}` — the full record for one facility by its stable
`f_` id, plus source `attributes` and reversible cross-silo `merge_history`.
| Param | Description |
| ------------- | -------------------------------------------------------------- |
| `facility_id` | The `f_...` id from a Search Facilities card (path parameter). |
```bash theme={null}
curl -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
"https://gdeltcloud.com/api/v2/facilities/f_581be6619920626d"
```
The same three tools are available on the **MCP server** as the `facilities` category
(`facilities_search`, `facilities_get`, `facilities_by_owner`) — see
[MCP → GDELT Cloud tools](/mcp/tools/gdelt-cloud). MCP inherits the same `can_use_facilities`
gate.