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

# Energy Infrastructure Workflow

> Use GEM Energy Data with Events and Stories to analyze physical infrastructure exposure.

## When to use

Use this workflow when the question involves physical energy assets, ownership exposure, country energy mix, infrastructure near an incident, or cross-border pipelines and terminals.

## The four-step flow

```
SUMMARIZE -> MAP -> SEARCH -> DETAIL
OWNER SEARCH -> OWNER DETAIL -> OWNER PORTFOLIO
```

1. **Summarize** with `/api/v2/energy/assets/summary` to understand the asset mix by tracker, country, status, fuel, or decade.
2. **Map** with `/api/v2/energy/assets/map` to choose the geography level. World and region views return country aggregates; a single-country view returns individual pins.
3. **Search** with `/api/v2/energy/assets` to retrieve asset cards with capacity, status, owner arrays, GEM Wiki URLs, and API detail links.
4. **Detail** with `/api/v2/energy/assets/{tracker}/{gem_id}` when you need tracker-specific fields from the raw source record.

For ownership-first questions, search owners before searching assets:

1. **Owner search** with `/api/v2/energy/owners?search=...` to resolve a company, ministry, state owner, person, or investment vehicle to a canonical GEM Entity ID.
2. **Owner detail** with `/api/v2/energy/owners/{entity_id}` to inspect registration/headquarters metadata, parent entities, external IDs, and portfolio summary.
3. **Owner portfolio** with `/api/v2/energy/assets?owner_entity_id=...&asset_class=all` to retrieve the underlying assets across trackers.

## REST examples

Country energy mix:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/energy/assets/summary?country=Germany&group_by=tracker&operating_only=true" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

Operating assets near an incident location:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/energy/assets?near=33.5,44.5,75&operating_only=true&limit=25" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

Owner exposure:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/energy/owners?search=Vattenfall&limit=5" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

Owner detail and portfolio:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/energy/owners/E100002021305" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

curl "https://gdeltcloud.com/api/v2/energy/assets?owner_entity_id=E100002021305&asset_class=all&limit=50" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

Single-country map pins:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/energy/assets/map?country=United%20States&operating_only=true&map_limit=300" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Pair with Events and Stories

Energy Data is structural. Events and Stories are temporal. Combine them when you need to answer whether a current development affects physical infrastructure:

1. Search Events or Stories for the incident, conflict, policy, or weather signal.
2. Pull the primary event or story location.
3. Query `/api/v2/energy/assets?near=lat,lon,radius_km`.
4. Use detail records and GEM Wiki URLs for asset-level evidence.

## Interpretation checks

* Confirm unit family before comparing capacity.
* Use `asset_class=all` only when mobile assets such as LNG carriers are relevant.
* For pipelines and binational hydropower, remember that country filters match primary or secondary country.
* Use `/api/v2/energy/owners` or `owner_entity_id` for ownership questions; `owner_search` on assets is a fuzzy raw-string search and can mix subsidiaries, parents, and spelling variants.
* GEM tracker releases arrive only a few times per year, so use Energy Data for structural exposure rather than daily asset-change monitoring.
* Treat GEM source facts and GDELT Cloud derived rollups as separate citations.