GDELT Cloud Docs — Global Event Data API & MCP

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_ids, 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 (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 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`.

# 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).

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 inherits the same can_use_facilities gate.

Facilities

Events

Stories

Entities

Geography

Reference Data

Government

Energy

Briefs

Filings

Macro Finance

Maritime

Media Intelligence

Screening and Reference

China

Unified Search

AI Compute

Facilities

Taxonomy — the type & class enums

Endpoints

Search Facilities

Get Facility

​Taxonomy — the type & class enums

​Endpoints

​Search Facilities

​Get Facility

Taxonomy — the type & class enums

Endpoints

Search Facilities

Get Facility