---
title: "Search Facilities"
method: GET
path: "/api/v2/facilities"
tags: ["Facilities"]
---

# Search Facilities

`GET /api/v2/facilities`

Search the unified facilities directory — one row per real-world facility, projected from three source silos and unified on a stable `facility_id`: Global Energy Monitor energy assets (plants, mines, terminals, pipelines — geography + spine owners), World Port Index ports (geography, no owner), and Epoch AI data centers (owner, no geography in v1). Every facility carries its owners as spine `entity_id`s, so a plant / terminal / field / data center joins to the cross-source entity graph. Filter by name, leaf `type` or coarse `class`, source silo, country/region/continent, owner (name or spine entity_id), status, capacity (MW), and geography (`bbox` / `near`). Directory-only in v1; the facility × event fusion is a separate stream. Plan-gated: requires the `can_use_facilities` entitlement (Analyst plan and up); non-entitled plans receive 403 PLAN_REQUIRED.

## Query parameters

- `q` string
- `type` string[]
- `class` 'power' | 'extraction' | 'transport_logistics' | 'ports' | 'heavy_industry' | 'digital_infrastructure'
- `source` string[]
- `country` string
- `region` string
- `continent` string
- `entity` string
- `owner_entity_id` string
- `owner_search` string
- `status` string
- `capacity_mw_min` number
- `capacity_mw_max` number
- `has_geo` boolean
- `has_owner` boolean
- `bbox` string
- `near` string
- `sort` 'name' | 'capacity_desc' | 'capacity_asc' | 'recent' | 'country'
- `limit` integer
- `cursor` string

## Response `200`

Success

- FacilitiesListResponse
  - `success` boolean
  - `data` FacilityCard[]
    - `facility_id` string — Stable id (f_...) — pass to Get Facility.
    - `name` string
    - `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'
    - `facility_class` 'power' | 'extraction' | 'transport_logistics' | 'ports' | 'heavy_industry' | 'digital_infrastructure', nullable
    - `source_silo` 'gem' | 'maritime_ports' | 'epoch'
    - `gem_tracker` string, nullable — The originating GEM tracker (gem silo only).
    - `country_iso3` string, nullable
    - `lat` number, nullable — Null for geo-null silos (Epoch data centers in v1).
    - `lon` number, nullable
    - `address` string, nullable
    - `status` string, nullable — operating / construction / proposed / retired / … (varies by silo).
    - `capacity_mw` number, nullable — Power facilities + data centers only.
    - `owners` FacilityOwner[]
      - `entity_id` string, nullable — Spine entity_id — join key to /api/v2/entities and the cross-source graph.
      - `name` string, nullable
    - `attributes` object — Silo-specific extra fields (fuel, tier, capacity_unit, h100e, …).
    - `first_seen_date` string, nullable
    - `last_seen_date` string, nullable
    - `detail_url` string
    - `owner_portfolio_url` string, nullable — GET /api/v2/facilities?owner_entity_id=... — the owner's full portfolio.
  - `pagination` FacilityPagination
    - `limit` integer
    - `offset` integer
    - `returned` integer
    - `has_more` boolean
    - `next_cursor` string, nullable — Pass back as `cursor` for the next page.
  - `applied_filters` object — Echo of the resolved filters.

## Other responses

- `400` — Invalid facility filter (unknown type / class / source / sort).
- `401` — API key required. Include: Authorization: Bearer gdelt_sk_...
- `403` — The caller's plan does not carry the can_use_facilities entitlement (Analyst plan and up).
- `429` — Rate limit or quota exceeded.
- `500` — Failed to fetch facilities.

---

[API](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2.md) · [All operations](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gdeltcloud/gdelt-cloud-api-v2/revisions/01aaa6255180/schema)