GDELT Cloud Docs — Global Event Data API & MCP

Map Energy Assets

curl --request GET \
  --url https://gdeltcloud.com/api/v2/energy/assets/map \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://gdeltcloud.com/api/v2/energy/assets/map', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "mode": "aggregate",
  "data": [
    {
      "kind": "aggregate",
      "country_iso3": "USA",
      "country": "United States",
      "lat": 39.5,
      "lon": -98.35,
      "asset_count": 1200,
      "capacity_mw_total": 250000,
      "top_tracker": "solar",
      "trackers": [
        "coal_plants",
        "solar",
        "wind"
      ]
    }
  ],
  "filters_echo": {
    "tracker": [],
    "country_iso3": [
      "USA"
    ],
    "status": [],
    "tier": [],
    "fuel": [],
    "operating_only": false,
    "asset_class": "fixed"
  }
}

{
  "success": false,
  "error": "Invalid Energy map filter.",
  "code": "INVALID_BBOX"
}

{
  "error": "API key required. Include: Authorization: Bearer gdelt_sk_...",
  "code": "MISSING_API_KEY"
}

{
  "success": false,
  "error": "Rate limit or quota exceeded.",
  "code": "RATE_LIMITED"
}

{
  "success": false,
  "error": "Failed to fetch energy map.",
  "code": "INTERNAL_ERROR"
}

GET

api

energy

assets

map

Map Energy Assets

curl --request GET \
  --url https://gdeltcloud.com/api/v2/energy/assets/map \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://gdeltcloud.com/api/v2/energy/assets/map', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "mode": "aggregate",
  "data": [
    {
      "kind": "aggregate",
      "country_iso3": "USA",
      "country": "United States",
      "lat": 39.5,
      "lon": -98.35,
      "asset_count": 1200,
      "capacity_mw_total": 250000,
      "top_tracker": "solar",
      "trackers": [
        "coal_plants",
        "solar",
        "wind"
      ]
    }
  ],
  "filters_echo": {
    "tracker": [],
    "country_iso3": [
      "USA"
    ],
    "status": [],
    "tier": [],
    "fuel": [],
    "operating_only": false,
    "asset_class": "fixed"
  }
}

{
  "success": false,
  "error": "Invalid Energy map filter.",
  "code": "INVALID_BBOX"
}

{
  "error": "API key required. Include: Authorization: Bearer gdelt_sk_...",
  "code": "MISSING_API_KEY"
}

{
  "success": false,
  "error": "Rate limit or quota exceeded.",
  "code": "RATE_LIMITED"
}

{
  "success": false,
  "error": "Failed to fetch energy map.",
  "code": "INTERNAL_ERROR"
}

Authorizations

Authorization

string

header

required

GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....

Query Parameters

tracker

enum<string>

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. Full value list: https://docs.gdeltcloud.com/reference/enums#gem_heavy_industry_tracker The enum above is the UNION across every endpoint that shares this parameter: iron_steel_plants, cement_plants, chemical_plants, iron_ore_mines — ACCEPTED ONLY ON /api/v2/energy/assets, /api/v2/energy/assets/summary. Elsewhere they return 400. On this endpoint the accepted set is narrower than on the other endpoints that share this parameter: iron_steel_plants, cement_plants, chemical_plants, iron_ore_mines return 400 here.

Available options:

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

Example:

"coal_plants,solar"

country

string

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. Full value list: https://docs.gdeltcloud.com/reference/enums#country

Example:

"United States"

region

enum<string>

Plain English region. Expands to the same ISO-3 country list used by V2 Events.

Available options:

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

Example:

"Middle East"

continent

enum<string>

Plain English continent. Expands to the same ISO-3 country list used by V2 Events.

Available options:

Africa,

Asia,

Europe,

North America,

South America,

Oceania

Example:

"Asia"

status

enum<string>

Comma-separated GEM status values. Common values include operating, construction, pre-construction, permitted, announced, proposed, shelved, cancelled, retired, and mothballed. See Taxonomy & Codes — Energy. Full value list: https://docs.gdeltcloud.com/reference/enums#energy_status

Available options:

operating,

construction,

proposed,

permitted,

cancelled,

mothballed,

retired,

active,

underground gas storage,

on order,

mixed status,

announced,

pre-construction,

pre-permit,

in-development,

discovered,

exploration,

shelved,

cancelled - inferred 4 y,

shelved - inferred 2 y,

abandoned,

idle,

idled,

decommissioning

Example:

"operating,construction"

operating_only

boolean

default:false

Shorthand for status=operating.

tier

string

Comma-separated within-tracker tier values such as main, utility, distributed, below_threshold, closed, or sub_threshold. Observed vocabulary, measured 2026-08-10 (5 distinct values). Values outside it are accepted, not rejected. Discover current values: GET /api/v2/energy/assets/summary?group_by=tier. GEM's own coverage tier for an asset row (main sheet vs below-threshold vs closed, and the utility/distributed split on solar). The serve layer accepts it as a free comma list and does not validate it, so an unknown tier returns an empty 200 rather than a 400 — which is why it is published as a measurement rather than as an allowlist. Values seen in the corpus: https://docs.gdeltcloud.com/reference/enums#energy_tier

Example:

"main,utility"

fuel

enum<string>

Comma-separated fuel values. Matches the tracker-native fuel string or normalized cross-tracker fuel where populated. See Taxonomy & Codes — Energy. Full value list: https://docs.gdeltcloud.com/reference/enums#energy_fuel

Available options:

gas,

oil,

bioenergy,

coal,

solar,

wind,

nuclear,

hydropower,

geothermal

Example:

"coal,solar"

capacity_mw_min

number

Minimum MW capacity. Meaningful for power-generation trackers only.

Required range: x >= 0

capacity_mw_max

number

Maximum MW capacity. Meaningful for power-generation trackers only.

Required range: x >= 0

start_year_min

integer

Minimum asset start year.

Required range: 1700 <= x <= 2200

start_year_max

integer

Maximum asset start year.

Required range: 1700 <= x <= 2200

retired_year_min

integer

Minimum asset retired year.

Required range: 1700 <= x <= 2200

retired_year_max

integer

Maximum asset retired year.

Required range: 1700 <= x <= 2200

entity

string

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"

owner_search

string

Legacy — prefer the canonical entity param (still fully supported). Case-insensitive substring match against the raw owner string.

Example:

"ExxonMobil"

owner_entity_id

string

GEM Entity ID. Returns assets where the entity appears in owners, operators, or parents.

Example:

"E100002021305"

bbox

string

Viewport filter formatted as lat_min,lon_min,lat_max,lon_max.

Pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$

Example:

"30,-105,33,-100"

near

string

Proximity filter formatted as lat,lon,radius_km.

Pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,\d+(\.\d+)?$

Example:

"31.16,-102.9,50"

string

Case-insensitive substring match against asset name.

Example:

"Ranch Energy"

asset_class

enum<string>

default:fixed

Asset class. The default fixed excludes mobile LNG carriers; use mobile or all for vessels. Full value list: https://docs.gdeltcloud.com/reference/enums#energy_asset_class

Available options:

fixed,

mobile,

all

map_limit

integer

default:300

Fine-mode pin limit. Alias of fine_grained_limit.

Required range: 50 <= x <= 1000

fine_grained_limit

integer

default:300

Fine-mode pin limit. Alias of map_limit.

Required range: 50 <= x <= 1000

Response

Success

success

enum<boolean>

required

Available options:

true

mode

enum<string>

required

Available options:

aggregate,

fine

data

object[]

required

Option 1
Option 2

Show child attributes

filters_echo

object

required

Show child attributes

applied_filters

object

Events

Stories

Situations

Entities

Unified Search

Media Intelligence

Facilities

Monitors

Geography

Government

Political Offices

Filings

Reference Data

Energy

AI Compute

Macro Finance

Screening and Reference

China

Maritime

Atlas Intelligence

Briefs

Meta

Map Energy Assets

Authorizations

Query Parameters

Response