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

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



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/facilities
openapi: 3.0.3
info:
  title: GDELT Cloud API v2
  version: 2.0.0
  description: >-
    Clean v2 REST API for generated GDELT Cloud structured Events, clustered
    Stories, linked Entities, summaries, admin1 discovery, significance ranking,
    and paginated article evidence.


    Event significance is a family-scoped weighted blend, renormalized so every
    event family spans a true 0-1: each event's raw total is divided by the
    maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90,
    other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article
    evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled
    by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20,
    systemic importance 0.15, propagation potential 0.10, market sensitivity
    0.10. When magnitude is unmeasured its term AND its 0.20 weight are both
    dropped. The four CAMEO+ metrics are rubric scores produced by published
    formulas - ordinal ranking signals, not measurements, probabilities, or
    predicted price moves. goldstein_scale is one canonical public metric,
    populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful.
    Story linked_event_count is a Story-to-Event link aggregate, not a distinct
    Event total.
servers:
  - url: https://gdeltcloud.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - ApiKeyAuth: []
tags:
  - name: Events
    description: Coded CAMEO+ / conflict events — search, fetch, and summarize.
  - name: Stories
    description: Clustered narratives (stories) and their articles.
  - name: Entities
    description: >-
      People & organizations — resolve a name to an entity, then fetch its
      profile and tone.
  - name: Geography
    description: Admin-1 geography lookups.
  - name: Energy
    description: Global Energy Monitor assets + ownership registry.
  - name: Facilities
    description: >-
      Unified physical-asset directory — GEM energy assets + World Port Index
      ports + Epoch AI data centers on one keyed surface, resolved to spine
      owners. Plan-gated (Analyst plan and up).
  - name: Screening and Reference
    description: >-
      Restricted-party lists, screening, and ownership-chain exposure.
      Plan-gated (`can_use_screening` / `can_use_exposure`).
  - name: China
    description: >-
      China overseas development finance (AidData GCDF). Plan-gated
      (`can_use_china`).
  - name: Media Intelligence
    description: >-
      Entity tone (`can_use_tone`) and Share of Voice (`can_use_share_of_voice`)
      are plan-gated. Social signal remains an admin-only preview.
  - name: Filings
    description: >-
      SEC EDGAR filings, XBRL financials, and AI-extracted relations. Requires a
      plan with SEC filings access (`can_use_filings`) — the Corporate & Supply
      Chain plan and above.
  - name: Macro Finance
    description: >-
      FRED economic time series (catalog, point-in-time observations, releases).
      Plan-gated (`can_use_macro`).
  - name: Maritime
    description: >-
      AIS-derived vessel-flow signals across maritime chokepoints — chokepoint
      transits, last-known vessel positions, carriers, dwell, and AIS-dark gaps.
      Plan-gated (`can_use_maritime`).
  - name: Briefs
    description: Source-backed monitoring briefs.
paths:
  /api/v2/facilities:
    get:
      tags:
        - Facilities
      summary: Search Facilities
      description: >-
        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.
      operationId: search-facilities-v2
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Case-insensitive substring match on the facility name.
          example: Sabine Pass
        - name: type
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - 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
          description: >-
            One or more leaf facility types (comma-separated). Invalid values
            return 400 INVALID_ENUM listing the accepted set.
          example: lng_terminal,port
        - name: class
          in: query
          required: false
          schema:
            type: string
            enum:
              - power
              - extraction
              - transport_logistics
              - ports
              - heavy_industry
              - digital_infrastructure
          description: Coarse class filter — grabs every leaf type in the class.
          example: digital_infrastructure
        - name: source
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - gem
                - maritime_ports
                - epoch
          description: >-
            Restrict to one or more source silos: gem (energy assets),
            maritime_ports (WPI ports), epoch (AI data centers).
          example: gem
        - name: country
          in: query
          required: false
          schema:
            type: string
          description: >-
            One or more country names or ISO-2/ISO-3 codes (comma-separated).
            Matches the facility's primary or secondary country.
          example: US
        - name: region
          in: query
          required: false
          schema:
            type: string
          description: >-
            One plain-English region (e.g. Middle East, South Asia). Expanded to
            its ISO-3 country list.
          example: Middle East
        - name: continent
          in: query
          required: false
          schema:
            type: string
          description: >-
            One plain-English continent (Asia, Europe, Africa, North America,
            South America, Oceania).
          example: Europe
        - name: entity
          in: query
          required: false
          schema:
            type: string
          description: >-
            Canonical owner selector — the same `entity` value works across
            endpoints (facilities, energy, gov). Pass a spine entity id (e_...,
            from /api/v2/search) for an EXACT owner match, or any name for a
            case-insensitive fuzzy owner-name match. Preferred over the legacy
            `owner_search` / `owner_entity_id` params below.
          example: Aramco
        - name: owner_entity_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Spine entity_id (e_...). Returns facilities this entity
            owns/operates. Also expressible as the canonical `entity=<e_ id>`.
            Resolve a name via /api/v2/search.
          example: e_a4db9cd53edee666
        - name: owner_search
          in: query
          required: false
          deprecated: true
          schema:
            type: string
          description: >-
            Legacy — prefer the canonical `entity` param (still fully
            supported). Case-insensitive substring match on the owner name (no
            id needed).
          example: Aramco
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: >-
            One or more operating-status values (comma-separated,
            case-insensitive): operating, construction, proposed, retired,
            cancelled… Vocabulary varies by silo.
          example: operating
        - name: capacity_mw_min
          in: query
          required: false
          schema:
            type: number
            minimum: 0
          description: >-
            Minimum capacity in MW (power facilities + data centers carry MW;
            ports/pipelines/extraction do not and are excluded when set).
        - name: capacity_mw_max
          in: query
          required: false
          schema:
            type: number
            minimum: 0
          description: Maximum capacity in MW.
        - name: has_geo
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            true → only facilities with coordinates (excludes Epoch data
            centers, geo-null in v1); false → only those without.
        - name: has_owner
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            true → only facilities with a resolved spine owner (excludes
            maritime ports); false → only those without.
        - name: bbox
          in: query
          required: false
          schema:
            type: string
          description: >-
            Geographic viewport 'lat_min,lon_min,lat_max,lon_max'. Geo-null
            facilities are excluded.
          example: 24,49,30,57
        - name: near
          in: query
          required: false
          schema:
            type: string
          description: >-
            Proximity query 'lat,lon,radius_km' — facilities within the radius
            of a point.
          example: 29.3,-94.8,400
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - name
              - capacity_desc
              - capacity_asc
              - recent
              - country
            default: name
          description: Result ordering.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Facility cards per page (max 100). Page deeper with cursor.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Pagination cursor from pagination.next_cursor on the previous
            response.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacilitiesListResponse'
              examples:
                facilities:
                  value:
                    success: true
                    data:
                      - facility_id: f_8b0dcc8be8d5aa98
                        name: AGP LNG Terminal
                        facility_type: lng_terminal
                        facility_class: transport_logistics
                        source_silo: gem
                        gem_tracker: lng_terminals
                        country_iso3: USA
                        lat: null
                        lon: null
                        status: proposed
                        capacity_mw: null
                        owners:
                          - entity_id: null
                            name: American Gas Partners Inc
                        attributes:
                          fuel: natural_gas
                          tier: main
                          capacity_unit: mtpa
                          start_year: null
                        first_seen_date: '2026-07-09'
                        last_seen_date: '2026-07-09'
                        detail_url: /api/v2/facilities/f_8b0dcc8be8d5aa98
                    pagination:
                      limit: 1
                      offset: 0
                      returned: 1
                      has_more: true
                      next_cursor: '1'
                    applied_filters:
                      countries:
                        - USA
                      type:
                        - lng_terminal
                      class: []
                      source: []
                      owner_entity_id: null
                      owner_search: null
                      q: null
                      status: []
                      capacity_mw_min: null
                      capacity_mw_max: null
                      has_geo: null
                      has_owner: null
                      sort: name
        '400':
          description: Invalid facility filter (unknown type / class / source / sort).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: >-
                      Invalid type 'power_plant'. Accepted: coal_plant,
                      oil_gas_plant, nuclear_plant, …, port, data_center
                    code: INVALID_ENUM
        '401':
          description: 'API key required. Include: Authorization: Bearer gdelt_sk_...'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    error: >-
                      API key required. Include: Authorization: Bearer
                      gdelt_sk_...
                    code: MISSING_API_KEY
        '403':
          description: >-
            The caller's plan does not carry the can_use_facilities entitlement
            (Analyst plan and up).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Your plan does not include the Facilities data source.
                    code: PLAN_REQUIRED
        '429':
          description: Rate limit or quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Rate limit or quota exceeded.
                    code: RATE_LIMITED
        '500':
          description: Failed to fetch facilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Failed to fetch facilities.
                    code: INTERNAL_ERROR
      security:
        - ApiKeyAuth: []
components:
  schemas:
    FacilitiesListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/FacilityCard'
        pagination:
          $ref: '#/components/schemas/FacilityPagination'
        applied_filters:
          type: object
          description: Echo of the resolved filters.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        code:
          type: string
        details:
          type: object
          description: >-
            Recoverable validation context when available, such as param,
            invalid_value, accepted_values, nearest_values, and a corrected
            example.
          additionalProperties: true
    FacilityCard:
      type: object
      description: >-
        One real-world facility in the unified directory, projected from a
        source silo and unified on a stable facility_id.
      properties:
        facility_id:
          type: string
          description: Stable id (f_...) — pass to Get Facility.
          example: f_8b0dcc8be8d5aa98
        name:
          type: string
          example: AGP LNG Terminal
        facility_type:
          type: string
          enum:
            - 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
          example: lng_terminal
        facility_class:
          type: string
          nullable: true
          enum:
            - power
            - extraction
            - transport_logistics
            - ports
            - heavy_industry
            - digital_infrastructure
          example: transport_logistics
        source_silo:
          type: string
          enum:
            - gem
            - maritime_ports
            - epoch
          example: gem
        gem_tracker:
          type: string
          nullable: true
          description: The originating GEM tracker (gem silo only).
          example: lng_terminals
        country_iso3:
          type: string
          nullable: true
          example: USA
        lat:
          type: number
          nullable: true
          description: Null for geo-null silos (Epoch data centers in v1).
        lon:
          type: number
          nullable: true
        address:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
          description: operating / construction / proposed / retired / … (varies by silo).
          example: proposed
        capacity_mw:
          type: number
          nullable: true
          description: Power facilities + data centers only.
          example: 169
        owners:
          type: array
          items:
            $ref: '#/components/schemas/FacilityOwner'
        attributes:
          type: object
          description: Silo-specific extra fields (fuel, tier, capacity_unit, h100e, …).
        first_seen_date:
          type: string
          nullable: true
        last_seen_date:
          type: string
          nullable: true
        detail_url:
          type: string
          example: /api/v2/facilities/f_8b0dcc8be8d5aa98
        owner_portfolio_url:
          type: string
          nullable: true
          description: >-
            GET /api/v2/facilities?owner_entity_id=... — the owner's full
            portfolio.
          example: /api/v2/facilities?owner_entity_id=e_a4db9cd53edee666
    FacilityPagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        returned:
          type: integer
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
          description: Pass back as `cursor` for the next page.
    FacilityOwner:
      type: object
      description: >-
        An owner / operator of a facility. entity_id is the spine e_ id (null
        for owner-name-only rows, e.g. maritime ports carry no owner and some
        GEM owners resolve a name but not a spine id yet).
      properties:
        entity_id:
          type: string
          nullable: true
          description: >-
            Spine entity_id — join key to /api/v2/entities and the cross-source
            graph.
          example: e_a4db9cd53edee666
        name:
          type: string
          nullable: true
          example: Alibaba
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````