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

# Summarize Energy Assets

> Aggregate counts and MW rollups across Energy assets. Summary endpoints use structured filters only. capacity_mw fields are meaningful for power-generation trackers; constrain tracker when comparing capacity across unit families.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/energy/assets/summary
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/summary:
    get:
      tags:
        - Energy
      summary: Summarize Energy Assets
      description: >-
        Aggregate counts and MW rollups across Energy assets. Summary endpoints
        use structured filters only. capacity_mw fields are meaningful for
        power-generation trackers; constrain tracker when comparing capacity
        across unit families.
      operationId: summarize-energy-assets-v2
      parameters:
        - $ref: '#/components/parameters/energyGroupBy'
        - $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/energyAssetClass'
        - $ref: '#/components/parameters/energySummaryLimit'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyAssetsSummaryResponse'
              examples:
                summary:
                  value:
                    success: true
                    group_by: tracker
                    data:
                      - bucket: solar
                        bucket_kind: tracker
                        asset_count: 103940
                        capacity_mw_total: 210000
                        capacity_mw_avg: 82.4
                        capacity_mw_max: 3500
                        capacity_mw_min: 1
                        status_counts:
                          operating: 65000
                          construction: 7000
                          proposed: 28000
                          cancelled: 2000
                          retired: 100
        '400':
          description: Invalid Energy summary filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Invalid Energy summary filter.
                    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
        '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 summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Failed to fetch energy summary.
                    code: INTERNAL_ERROR
      security:
        - ApiKeyAuth: []
components:
  parameters:
    energyGroupBy:
      name: group_by
      in: query
      required: false
      schema:
        type: string
        enum:
          - country
          - region
          - continent
          - tracker
          - status
          - start_year_decade
          - fuel
          - tier
        default: tracker
      description: Summary aggregation dimension.
      example: tracker
    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
    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
    energySummaryLimit:
      name: summary_limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
      description: Number of summary buckets to return.
      example: 50
  schemas:
    EnergyAssetsSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - group_by
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        group_by:
          type: string
          enum:
            - country
            - region
            - continent
            - tracker
            - status
            - start_year_decade
            - fuel
            - tier
        data:
          type: array
          items:
            $ref: '#/components/schemas/EnergyAssetSummaryBucket'
        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
    EnergyAssetSummaryBucket:
      type: object
      additionalProperties: false
      required:
        - bucket
        - bucket_kind
        - asset_count
        - capacity_mw_total
        - capacity_mw_avg
        - capacity_mw_max
        - capacity_mw_min
        - status_counts
      properties:
        bucket:
          type: string
          nullable: true
        bucket_kind:
          type: string
        asset_count:
          type: number
        capacity_mw_total:
          type: number
        capacity_mw_avg:
          type: number
          nullable: true
        capacity_mw_max:
          type: number
          nullable: true
        capacity_mw_min:
          type: number
          nullable: true
        status_counts:
          type: object
          additionalProperties: false
          required:
            - operating
            - construction
            - proposed
            - cancelled
            - retired
          properties:
            operating:
              type: number
            construction:
              type: number
            proposed:
              type: number
            cancelled:
              type: number
            retired:
              type: number
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````