---
title: "Grid topology analysis (nodes, edges, graph metrics, optional path analysis)"
method: POST
path: "/api/osm-geo/grid-topology"
tags: ["OSM Geo (OpenStreetMap)"]
---

# Grid topology analysis (nodes, edges, graph metrics, optional path analysis)

`POST /api/osm-geo/grid-topology`

## Request

- Base URL: `https://api.cernion.de`
- URL: `https://api.cernion.de/api/osm-geo/grid-topology`
- Auth: none declared

Analyses the visible grid topology within an area by extracting nodes (substations, transformers) and edges (lines, cables) directly from OpenStreetMap via Overpass (src/osm-grid-topology.js — computed locally, no external mcp.cernion.de dependency for this action).

**Graph model:** nodes = OSM elements tagged `power=substation`/`power=transformer`; edges = derived by walking each `power=line|cable|minor_line` way's ordered node list and connecting consecutive pairs of those nodes found along it. Towers/poles are not modelled as graph nodes, so a line touching zero or one node of interest within the bbox contributes no edge from that way — a legitimate boundary effect, not missing data.

**Graph metrics returned:**
- Node and edge counts, average node degree
- Topology type: `RADIAL` (indicator < 0.5), `MIXED` (0.5–0.7), `RING` (> 0.7 — higher redundancy). Indicator = cyclomatic number (E − V + components) normalised by edge count.
- Voltage-level breakdown (NS/MS/HS/EHS, classified from the OSM `voltage` tag)

**Optional path analysis** (`includePathAnalysis: true`): shortest path between `fromOsmId` → `toOsmId` (Dijkstra over derived edge lengths) with hop count, total length, and confidence rating.

**Optional raw graph data** (`includeGraphData: true`): full node/edge list for downstream processing.

**Scope input:** at least one of `location` (place name), `postalCode`, `boundingBox`, or `gridOperator` name. Named-place/postalCode/gridOperator scopes are forward-geocoded to a bounding box via Nominatim; `boundingBox` is used directly.

**Data:** © OpenStreetMap contributors, [ODbL 1.0](https://opendatacommons.org/licenses/odbl/)

## Query parameters

- `token` string

## Request body

- object
  - `location` string: Area name (Gemeinde, Stadt, Landkreis).
  - `postalCode` string: German PLZ (postal code). Combined with location when both are provided (e.g. "74909 Meckesheim"). Can be used alone for PLZ-scoped queries.
  - `boundingBox` object: Explicit geographic bounding box — directly compatible with vnbdigital_lookup bbox.
    - `north` number
    - `south` number
    - `east` number
    - `west` number
  - `gridOperator` string: VNB name — used as OSM area name.
  - `voltageLevel` string: Restrict analysis to one voltage level: NS, MS, HS, EHS.
  - `fromOsmId` string: Start-node OSM ID for path analysis (e.g. "node/1234567").
  - `toOsmId` string: Target-node OSM ID for path analysis.
  - `includePathAnalysis` boolean: Compute shortest path between fromOsmId → toOsmId.
  - `includeGraphData` boolean: Include raw node/edge list for downstream processing.
  - `token` string: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

## Response `200`

Topology analysis returned successfully

---

[API](https://skmtc.dev/cernion/apis/cernion-energy-tools-api.md) · [All operations](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/revisions/cdb94473b538?raw)