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

> Search the Global Energy Monitor ownership registry for canonical owner entities. Use this endpoint to resolve a company, government owner, person, or investment vehicle to a GEM Entity ID before calling owner portfolio or exposure endpoints.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/energy/owners
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/owners:
    get:
      tags:
        - Energy
      summary: Search Energy Owners
      description: >-
        Search the Global Energy Monitor ownership registry for canonical owner
        entities. Use this endpoint to resolve a company, government owner,
        person, or investment vehicle to a GEM Entity ID before calling owner
        portfolio or exposure endpoints.
      operationId: search-energy-owners-v2
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Search owner name, abbreviation, GEM Entity ID, or external ID.
        - name: search
          in: query
          schema:
            type: string
          description: Alias for q.
        - name: entity_id
          in: query
          schema:
            type: string
          description: Exact GEM ownership entity ID.
        - name: country
          in: query
          schema:
            type: string
          description: >-
            Country filter — matches an owner's registration or headquarters
            country. Accepts a country name, ISO-2, or ISO-3 via the shared
            `resolveCountryInput` layer (combinable with `region`/`continent`);
            an unresolvable value returns `400 INVALID_COUNTRY`.
        - name: region
          in: query
          schema:
            type: string
          description: >-
            Region expanded to ISO-3 countries; matches registration or
            headquarters country.
        - name: continent
          in: query
          schema:
            type: string
          description: >-
            Continent expanded to ISO-3 countries; matches registration or
            headquarters country.
        - name: entity_type
          in: query
          schema:
            type: string
          description: Comma-separated GEM owner entity types.
        - name: publicly_listed
          in: query
          schema:
            type: boolean
          description: Filter by public-listing status.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Rows per page.
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor from pagination.next_cursor.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnergyOwnersListResponse'
              examples:
                owners:
                  value:
                    success: true
                    data:
                      - entity_id: E100002021513
                        full_name: Pacifico Energy Group LLC
                        name: Pacifico Energy Group LLC
                        abbreviation: null
                        entity_type: company
                        legal_entity_type: company
                        publicly_listed: false
                        registration_country_iso3: USA
                        headquarters_country_iso3: USA
                        gem_parent_ids: []
                        external_ids: {}
                        portfolio_url: /api/v2/energy/assets?owner_entity_id=E100002021513
                        detail_url: /api/v2/energy/owners/E100002021513
                    pagination:
                      limit: 25
                      cursor: null
                      next_cursor: null
        '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
        '500':
          description: Failed to fetch energy owners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  value:
                    success: false
                    error: Failed to fetch energy owners.
                    code: INTERNAL_ERROR
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EnergyOwnersListResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - data
        - pagination
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/EnergyOwnerCard'
        pagination:
          $ref: '#/components/schemas/EnergyPagination'
        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
    EnergyOwnerCard:
      type: object
      additionalProperties: true
      required:
        - entity_id
        - full_name
        - name
        - entity_type
        - legal_entity_type
        - gem_parents
        - gem_parent_ids
        - external_ids
        - dataset_version
        - source_file
      properties:
        entity_id:
          type: string
        full_name:
          type: string
        name:
          type: string
        name_local:
          type: string
          nullable: true
        name_other:
          type: string
          nullable: true
        abbreviation:
          type: string
          nullable: true
        entity_type:
          type: string
        legal_entity_type:
          type: string
        publicly_listed:
          type: boolean
          nullable: true
        home_page:
          type: string
          nullable: true
        registration_country:
          type: string
        registration_country_iso3:
          type: string
        registration_subdivision:
          type: string
          nullable: true
        headquarters_country:
          type: string
        headquarters_country_iso3:
          type: string
        headquarters_subdivision:
          type: string
          nullable: true
        gem_parents:
          type: array
          items:
            type: string
        gem_parent_ids:
          type: array
          items:
            type: string
        external_ids:
          type: object
          additionalProperties:
            type: string
        dataset_version:
          type: string
        source_file:
          type: string
        ingested_at:
          type: string
        portfolio_url:
          type: string
          nullable: true
        detail_url:
          type: string
          nullable: true
        portfolio_summary:
          $ref: '#/components/schemas/EnergyOwnerPortfolioSummary'
        exposure_summary:
          type: array
          items:
            $ref: '#/components/schemas/EnergyOwnerExposureSummary'
    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
    EnergyOwnerPortfolioSummary:
      type: object
      additionalProperties: false
      required:
        - asset_count
        - capacity_mw_total
        - by_tracker
      properties:
        asset_count:
          type: number
        capacity_mw_total:
          type: number
        by_tracker:
          type: array
          items:
            $ref: '#/components/schemas/EnergyOwnerPortfolioTracker'
    EnergyOwnerExposureSummary:
      type: object
      additionalProperties: false
      required:
        - lens
        - exposed
        - direct
        - via_entity_ids
        - lists
        - china_edges
      properties:
        lens:
          type: string
          enum:
            - sanctions
            - china
            - state_owned
        exposed:
          type: boolean
        direct:
          type: boolean
        via_entity_ids:
          type: array
          items:
            type: string
        lists:
          type: array
          items:
            type: string
        china_edges:
          type: array
          items:
            type: string
    EnergyOwnerPortfolioTracker:
      type: object
      additionalProperties: false
      required:
        - tracker
        - asset_count
        - capacity_mw_total
        - operating_count
        - planned_count
        - inactive_count
      properties:
        tracker:
          type: string
        asset_count:
          type: number
        capacity_mw_total:
          type: number
        operating_count:
          type: number
        planned_count:
          type: number
        inactive_count:
          type: number
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````