> ## 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 Energy Assets

> Search Global Energy Monitor energy-infrastructure assets across all 15 trackers. Returns clean asset cards with native capacity, MW capacity where meaningful, normalized geography, ownership arrays, GEM Wiki URLs, and detail/API links.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/energy/assets
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/energy/assets:
    get:
      tags:
        - Energy
      summary: Search Energy Assets
      description: >-
        Search Global Energy Monitor energy-infrastructure assets across all 15
        trackers. Returns clean asset cards with native capacity, MW capacity
        where meaningful, normalized geography, ownership arrays, GEM Wiki URLs,
        and detail/API links.
      operationId: search-energy-assets-v2
      parameters:
        - $ref: '#/components/parameters/energyTracker'
        - $ref: '#/components/parameters/energyCountry'
        - $ref: '#/components/parameters/energyRegion'
        - $ref: '#/components/parameters/energyContinent'
        - $ref: '#/components/parameters/energyStatus'
        - $ref: '#/components/parameters/energyOperatingOnly'
        - $ref: '#/components/parameters/energyTier'
        - $ref: '#/components/parameters/energyFuel'
        - $ref: '#/components/parameters/energyCapacityMwMin'
        - $ref: '#/components/parameters/energyCapacityMwMax'
        - $ref: '#/components/parameters/energyStartYearMin'
        - $ref: '#/components/parameters/energyStartYearMax'
        - $ref: '#/components/parameters/energyRetiredYearMin'
        - $ref: '#/components/parameters/energyRetiredYearMax'
        - $ref: '#/components/parameters/energyEntity'
        - $ref: '#/components/parameters/energyOwnerSearch'
        - $ref: '#/components/parameters/energyOwnerEntityId'
        - $ref: '#/components/parameters/energyBbox'
        - $ref: '#/components/parameters/energyNear'
        - $ref: '#/components/parameters/energySearch'
        - $ref: '#/components/parameters/energyAssetClass'
        - $ref: '#/components/parameters/energySort'
        - $ref: '#/components/parameters/energyLimit'
        - $ref: '#/components/parameters/energyCursor'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyAssetsListResponse'
              examples:
                assets:
                  value:
                    success: true
                    data:
                      - id: oil_gas_plants:G100001090366
                        gem_id: G100001090366
                        tracker: oil_gas_plants
                        tier: main
                        asset_class: fixed
                        name: GW Ranch Energy Center
                        name_local: null
                        name_other: null
                        status: pre-construction
                        status_detail: null
                        start_year: 2028
                        retired_year: null
                        fuel: 'fossil gas: natural gas'
                        capacity:
                          value: 5000
                          unit: MW
                          mw: 5000
                          mw_secondary: null
                        geo:
                          country: United States
                          country_iso3: USA
                          secondary_country_iso3: null
                          region: North America
                          subregion: Northern America
                          continent: North America
                          state_province: Texas
                          city: Fort Stockton
                          lat: 31.16
                          lon: -102.9
                          location_accuracy: exact
                        owners_raw: Pacifico GW LLC
                        owners:
                          - name: Pacifico GW LLC
                            entity_id: E100002021305
                            stake_pct: null
                        operators_raw: null
                        operators: []
                        parents_raw: Pacifico Energy Group LLC
                        parents:
                          - name: Pacifico Energy Group LLC
                            entity_id: E100002021513
                            stake_pct: null
                        wiki_url: https://www.gem.wiki/GW_Ranch_Energy_Center
                        last_updated: '2026-01-15'
                        detail_url: /energy/oil_gas_plants/G100001090366
                        api_url: /api/v2/energy/assets/oil_gas_plants/G100001090366
                    pagination:
                      limit: 25
                      cursor: null
                      next_cursor: null
                    sort: capacity_desc
                    filters_echo:
                      tracker:
                        - oil_gas_plants
                      country_iso3:
                        - USA
                      status:
                        - pre-construction
                      tier: []
                      fuel: []
                      capacity_mw_min: null
                      capacity_mw_max: null
                      start_year_min: null
                      start_year_max: null
                      owner_search: null
                      owner_entity_id: null
                      bbox: null
                      near: null
                      search: null
                      operating_only: false
                      asset_class: fixed
        '400':
          description: Invalid Energy filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Invalid Energy filter.
                    code: INVALID_TRACKER
        '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
        '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 energy assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Failed to fetch energy assets.
                    code: INTERNAL_ERROR
      security:
        - ApiKeyAuth: []
components:
  parameters:
    energyTracker:
      name: tracker
      in: query
      required: false
      schema:
        type: string
        example: coal_plants,solar
      description: >-
        Comma-separated GEM trackers. Valid values: coal_plants, coal_mines,
        coal_terminals, oil_gas_plants, oil_gas_extraction, lng_terminals,
        nuclear, geothermal, bioenergy, hydropower, solar, wind, gas_pipelines,
        oil_pipelines, lng_carriers. Omit for all trackers. All trackers:
        [Taxonomy & Codes —
        Energy](/api-reference/taxonomy#energy-vocabularies).
      example: coal_plants,solar
    energyCountry:
      name: country
      in: query
      required: false
      schema:
        type: string
        example: United States
      description: >-
        Country filter, resolved through the shared `resolveCountryInput` layer:
        a country name (`United States`), ISO-2 (`US`), ISO-3 (`USA`), or legacy
        alias all work. Filters primary or secondary country for cross-border
        assets; combinable with `region`/`continent` and an unresolvable value
        returns `400 INVALID_COUNTRY`.
      example: United States
    energyRegion:
      name: region
      in: query
      required: false
      schema:
        type: string
        example: Middle East
        enum:
          - 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
      description: >-
        Plain English region. Expands to the same ISO-3 country list used by V2
        Events.
      example: Middle East
    energyContinent:
      name: continent
      in: query
      required: false
      schema:
        type: string
        example: Asia
        enum:
          - Africa
          - Asia
          - Europe
          - North America
          - South America
          - Oceania
      description: >-
        Plain English continent. Expands to the same ISO-3 country list used by
        V2 Events.
      example: Asia
    energyStatus:
      name: status
      in: query
      required: false
      schema:
        type: string
        example: operating,construction
      description: >-
        Comma-separated GEM status values. Common values include operating,
        construction, pre-construction, permitted, announced, proposed, shelved,
        cancelled, retired, and mothballed. See [Taxonomy & Codes —
        Energy](/api-reference/taxonomy#energy-vocabularies).
      example: operating
    energyOperatingOnly:
      name: operating_only
      in: query
      required: false
      schema:
        type: boolean
        default: false
      description: Shorthand for status=operating.
      example: true
    energyTier:
      name: tier
      in: query
      required: false
      schema:
        type: string
        example: main,utility
      description: >-
        Comma-separated within-tracker tier values such as main, utility,
        distributed, below_threshold, closed, or sub_threshold.
      example: main
    energyFuel:
      name: fuel
      in: query
      required: false
      schema:
        type: string
        example: coal,solar
      description: >-
        Comma-separated fuel values. Matches the tracker-native fuel string or
        normalized cross-tracker fuel where populated. See [Taxonomy & Codes —
        Energy](/api-reference/taxonomy#energy-vocabularies).
      example: coal
    energyCapacityMwMin:
      name: capacity_mw_min
      in: query
      required: false
      schema:
        type: number
        minimum: 0
      description: Minimum MW capacity. Meaningful for power-generation trackers only.
      example: 100
    energyCapacityMwMax:
      name: capacity_mw_max
      in: query
      required: false
      schema:
        type: number
        minimum: 0
      description: Maximum MW capacity. Meaningful for power-generation trackers only.
      example: 5000
    energyStartYearMin:
      name: start_year_min
      in: query
      required: false
      schema:
        type: integer
        minimum: 1700
        maximum: 2200
      description: Minimum asset start year.
      example: 2000
    energyStartYearMax:
      name: start_year_max
      in: query
      required: false
      schema:
        type: integer
        minimum: 1700
        maximum: 2200
      description: Maximum asset start year.
      example: 2030
    energyRetiredYearMin:
      name: retired_year_min
      in: query
      required: false
      schema:
        type: integer
        minimum: 1700
        maximum: 2200
      description: Minimum asset retired year.
      example: 2000
    energyRetiredYearMax:
      name: retired_year_max
      in: query
      required: false
      schema:
        type: integer
        minimum: 1700
        maximum: 2200
      description: Maximum asset retired year.
      example: 2030
    energyEntity:
      name: entity
      in: query
      required: false
      schema:
        type: string
        example: ArcelorMittal
      description: >-
        Canonical owner selector — the same `entity` value works across
        endpoints. Pass a spine entity id (e_...) for an EXACT match against an
        asset's owners, operators, or parents, or any name for a
        case-insensitive fuzzy owner-name match. Preferred over the legacy
        `owner_search` param.
      example: ArcelorMittal
    energyOwnerSearch:
      name: owner_search
      in: query
      required: false
      deprecated: true
      schema:
        type: string
        example: ExxonMobil
      description: >-
        Legacy — prefer the canonical `entity` param (still fully supported).
        Case-insensitive substring match against the raw owner string.
      example: ExxonMobil
    energyOwnerEntityId:
      name: owner_entity_id
      in: query
      required: false
      schema:
        type: string
        example: E100002021305
      description: >-
        GEM Entity ID. Returns assets where the entity appears in owners,
        operators, or parents.
      example: E100002021305
    energyBbox:
      name: bbox
      in: query
      required: false
      schema:
        type: string
        pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$
        example: 30,-105,33,-100
      description: Viewport filter formatted as lat_min,lon_min,lat_max,lon_max.
      example: 30,-105,33,-100
    energyNear:
      name: near
      in: query
      required: false
      schema:
        type: string
        pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,\d+(\.\d+)?$
        example: 31.16,-102.9,50
      description: Proximity filter formatted as lat,lon,radius_km.
      example: 31.16,-102.9,50
    energySearch:
      name: search
      in: query
      required: false
      schema:
        type: string
        example: Ranch Energy
      description: Case-insensitive substring match against asset name.
      example: Ranch Energy
    energyAssetClass:
      name: asset_class
      in: query
      required: false
      schema:
        type: string
        enum:
          - fixed
          - mobile
          - all
        default: fixed
      description: >-
        Asset class. The default fixed excludes mobile LNG carriers; use mobile
        or all for vessels.
      example: fixed
    energySort:
      name: sort
      in: query
      required: false
      schema:
        type: string
        enum:
          - capacity_desc
          - capacity_asc
          - start_year_desc
          - start_year_asc
          - recent
          - name
        default: capacity_desc
      description: List sort order.
      example: capacity_desc
    energyLimit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      description: Number of asset cards to return.
      example: 25
    energyCursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        example: '25'
      description: Pagination cursor from pagination.next_cursor.
      example: '25'
  schemas:
    EnergyAssetsListResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - data
        - pagination
        - sort
        - filters_echo
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/EnergyAssetCard'
        pagination:
          $ref: '#/components/schemas/EnergyPagination'
        sort:
          type: string
        filters_echo:
          $ref: '#/components/schemas/EnergyListFiltersEcho'
        applied_filters:
          type: object
    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
    EnergyAssetCard:
      type: object
      additionalProperties: false
      required:
        - id
        - gem_id
        - tracker
        - tier
        - asset_class
        - name
        - name_local
        - name_other
        - status
        - status_detail
        - start_year
        - retired_year
        - fuel
        - capacity
        - geo
        - owners_raw
        - owners
        - operators_raw
        - operators
        - parents_raw
        - parents
        - wiki_url
        - last_updated
        - detail_url
        - api_url
      properties:
        id:
          type: string
        gem_id:
          type: string
        tracker:
          type: string
          enum:
            - coal_plants
            - coal_mines
            - coal_terminals
            - oil_gas_plants
            - oil_gas_extraction
            - lng_terminals
            - nuclear
            - geothermal
            - bioenergy
            - hydropower
            - solar
            - wind
            - gas_pipelines
            - oil_pipelines
            - lng_carriers
        tier:
          type: string
          nullable: true
        asset_class:
          type: string
        name:
          type: string
        name_local:
          type: string
          nullable: true
        name_other:
          type: string
          nullable: true
        status:
          type: string
        status_detail:
          type: string
          nullable: true
        start_year:
          type: integer
          nullable: true
        retired_year:
          type: integer
          nullable: true
        fuel:
          type: string
          nullable: true
        capacity:
          $ref: '#/components/schemas/EnergyCapacity'
        geo:
          $ref: '#/components/schemas/EnergyAssetGeo'
        owners_raw:
          type: string
          nullable: true
        owners:
          type: array
          items:
            $ref: '#/components/schemas/EnergyOwnerEntry'
        operators_raw:
          type: string
          nullable: true
        operators:
          type: array
          items:
            $ref: '#/components/schemas/EnergyOwnerEntry'
        parents_raw:
          type: string
          nullable: true
        parents:
          type: array
          items:
            $ref: '#/components/schemas/EnergyOwnerEntry'
        wiki_url:
          type: string
          nullable: true
        last_updated:
          type: string
          nullable: true
        detail_url:
          type: string
        api_url:
          type: string
    EnergyPagination:
      type: object
      additionalProperties: false
      required:
        - limit
        - cursor
        - next_cursor
      properties:
        limit:
          type: integer
        cursor:
          type: string
          nullable: true
        next_cursor:
          type: string
          nullable: true
    EnergyListFiltersEcho:
      type: object
      additionalProperties: false
      required:
        - tracker
        - country_iso3
        - status
        - tier
        - fuel
        - capacity_mw_min
        - capacity_mw_max
        - start_year_min
        - start_year_max
        - owner_search
        - owner_entity_id
        - bbox
        - near
        - search
        - operating_only
        - asset_class
      properties:
        tracker:
          type: array
          items:
            type: string
        country_iso3:
          type: array
          items:
            type: string
        status:
          type: array
          items:
            type: string
        tier:
          type: array
          items:
            type: string
        fuel:
          type: array
          items:
            type: string
        capacity_mw_min:
          type: number
          nullable: true
        capacity_mw_max:
          type: number
          nullable: true
        start_year_min:
          type: number
          nullable: true
        start_year_max:
          type: number
          nullable: true
        owner_search:
          type: string
          nullable: true
        owner_entity_id:
          type: string
          nullable: true
        bbox:
          type: object
          nullable: true
          additionalProperties: false
          required:
            - latMin
            - lonMin
            - latMax
            - lonMax
          properties:
            latMin:
              type: number
            lonMin:
              type: number
            latMax:
              type: number
            lonMax:
              type: number
        near:
          type: object
          nullable: true
          additionalProperties: false
          required:
            - lat
            - lon
            - radiusKm
          properties:
            lat:
              type: number
            lon:
              type: number
            radiusKm:
              type: number
        search:
          type: string
          nullable: true
        operating_only:
          type: boolean
        asset_class:
          type: string
          enum:
            - fixed
            - mobile
            - all
    EnergyCapacity:
      type: object
      additionalProperties: false
      required:
        - value
        - unit
        - mw
        - mw_secondary
      properties:
        value:
          type: number
          nullable: true
        unit:
          type: string
        mw:
          type: number
          nullable: true
          description: Populated only for power-generation trackers.
        mw_secondary:
          type: number
          nullable: true
    EnergyAssetGeo:
      type: object
      additionalProperties: false
      required:
        - country
        - country_iso3
        - secondary_country_iso3
        - region
        - subregion
        - continent
        - state_province
        - city
        - lat
        - lon
        - location_accuracy
      properties:
        country:
          type: string
          nullable: true
        country_iso3:
          type: string
          nullable: true
        secondary_country_iso3:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        subregion:
          type: string
          nullable: true
        continent:
          type: string
          nullable: true
        state_province:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        lat:
          type: number
          nullable: true
        lon:
          type: number
          nullable: true
        location_accuracy:
          type: string
          nullable: true
    EnergyOwnerEntry:
      type: object
      additionalProperties: false
      required:
        - name
        - entity_id
        - stake_pct
      properties:
        name:
          type: string
        entity_id:
          type: string
          nullable: true
        stake_pct:
          type: number
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````