Layer 2 Geo-Architecture: physical grid infrastructure from OpenStreetMap via the Overpass API. Complements authoritative VNBDigital data (Layer 1) with visible substations, transformers, and lines. Data: © OpenStreetMap contributors, ODbL 1.0 — https://opendatacommons.org/licenses/odbl/
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/cernion-de:cernion-de-osm-geo-openstreetmap-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Cernion Energy Tools OSM Geo (OpenStreetMap) API
version: 0.99.22
description: 'MicroService Agent System for Energy Markets - REST API with AI integration.
CERNION_TOKEN: request at https://cernion.de/ or by email: dev@stromdao.com.
For the public instance at https://api.cernion.de/, create your token at https://cernion.de/cet-token/.'
servers:
- url: https://api.cernion.de
description: API Server
tags:
- name: OSM Geo (OpenStreetMap)
description: 'Layer 2 Geo-Architecture: physical grid infrastructure from OpenStreetMap via the Overpass API. Complements authoritative VNBDigital data (Layer 1) with visible substations, transformers, and lines. Data: © OpenStreetMap contributors, ODbL 1.0 — https://opendatacommons.org/licenses/odbl/'
paths:
/api/osm-geo/validate:
post:
summary: Geo-plausibility check for MaStR VNB assignment (L1 authoritative + L2 OSM)
tags:
- OSM Geo (OpenStreetMap)
operationId: osm_geo_validate
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Validation result returned successfully
content:
application/json:
example:
success: true
data:
mastrNummer: SEE900012345678
installation:
location:
lat: 49.481
lon: 8.432
installationType: solar
bruttoleistungKW: 9.9
registeredGridOperator: STROMDAO Netze GmbH
registeredGridOperatorId: SNB935578300972
validation:
verdict: CONSISTENT
confidenceScore: 72
flags: []
layer1_vnbdigital:
queried: true
status: QUERIED_SUCCESS
vnbFound: STROMDAO Netze GmbH
match: true
authoritative: true
layer2_osm:
queried: true
osmObjectsFound: 3
nearestSubstation:
osmId: node/123456789
distanceMeters: 184
type: distribution
operatorTag: STROMDAO
dominantOperator: STROMDAO
dominantOperatorShare: 1
radiusMeters: 500
dataQuality:
layer1Coverage: FULL
layer2Coverage: MEDIUM
osmDisclaimer: © OpenStreetMap contributors (ODbL 1.0)
description: 'Two-layer geographic plausibility check for the grid-operator assignment of a MaStR installation.
**Layer 1 (authoritative):** Coordinate → VNBDigital → expected grid operator for this location.
**Layer 2 (physical):** Coordinate → Overpass API → nearby substations / dominant operator tag.
Detects both **DEFINITIVE_MISASSIGNMENT** (L1 mismatch, authoritative) and **LIKELY_MISASSIGNMENT** (L2 OSM hint only).
**Input:** either `mastrNummer` (coordinates resolved automatically) **or** explicit `latitude` + `longitude`.
**Verdict values:**
- `CONSISTENT` — assignment plausible (L1 + L2 agree or no contradiction)
- `DEFINITIVE_MISASSIGNMENT` — VNBDigital points to a different operator (authoritative correction required)
- `LIKELY_MISASSIGNMENT` — OSM infrastructure tags suggest a different operator
- `UNCERTAIN` — contradictory signals, no clear verdict
- `INSUFFICIENT_DATA` — too few OSM objects for a reliable verdict
**OSM coverage note:** Typically 40–60 % of MS/NS infrastructure is mapped in OSM for Germany. The `dataQuality.coverageLabel` field carries a per-response quality estimate.
**Data:** © OpenStreetMap contributors, ODbL 1.0'
requestBody:
content:
application/json:
schema:
type: object
properties:
mastrNummer:
type: string
description: MaStR number (SEE…, SWE…, SBE…). Coordinates and VNB resolved automatically from the local DB.
example: SEE900012345678
latitude:
type: number
description: Latitude — required when mastrNummer is not provided.
example: 49.481
longitude:
type: number
description: Longitude — required when mastrNummer is not provided.
example: 8.432
registeredGridOperatorName:
type: string
description: Registered VNB name for the L1 comparison.
example: STROMDAO Netze GmbH
gridOperatorId:
type: string
description: MaStR ID of the VNB (SNB…).
example: SNB935578300972
radiusMeters:
type: number
description: OSM search radius in metres (max 5 000).
default: 500
example: 500
skipOsmLayer:
type: boolean
description: Only run L1 (no Overpass call). Faster for batch runs.
default: false
example: false
includeInfrastructureDetails:
type: boolean
description: Include the full list of found OSM objects in the response.
default: false
example: false
confidenceThreshold:
type: number
description: Minimum score for CONSISTENT verdict.
default: 40
example: 40
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
examples:
byMastrNummer:
summary: Minimal call — MaStR number only
value:
mastrNummer: SEE900012345678
l1Only:
summary: L1-only check (no Overpass, fast for batch)
value:
mastrNummer: SEE900012345678
skipOsmLayer: true
byCoordinates:
summary: Explicit coordinates with infrastructure details
value:
latitude: 49.481
longitude: 8.432
registeredGridOperatorName: STROMDAO Netze GmbH
radiusMeters: 800
includeInfrastructureDetails: true
/api/osm-geo/infrastructure-nearby:
post:
summary: Energy infrastructure near a location (sorted by distance)
tags:
- OSM Geo (OpenStreetMap)
operationId: osm_geo_infrastructureNearby
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Nearby infrastructure retrieved successfully
content:
application/json:
example:
success: true
data:
queryCenter:
lat: 49.481
lon: 8.432
radiusMeters: 1000
bboxConstrained: false
totalFound: 7
summary:
nearestSubstationMeters: 184
nearestNSConnectionMeters: 184
nearestMSConnectionMeters: 430
dominantOperator: STROMDAO
substationsFound: 4
osmCoverageQuality: MEDIUM
infrastructure:
- osmId: node/123456789
type: substation
subtype: distribution
distanceMeters: 184
location:
lat: 49.4826
lon: 8.4298
voltageLevel: NS
voltageIn: '20000'
voltageOut: '400'
operator: STROMDAO
name: UW Innenstadt
connectionSuitability: SUITABLE_NS
dataQuality:
coverageLabel: MEDIUM
disclaimer: © OpenStreetMap contributors (ODbL 1.0)
description: 'Returns all energy infrastructure (substations, transformers, lines, cables) within a defined radius, sorted by distance from the query centre.
Each object carries voltage level, operator tag, and a **`connectionSuitability`** assessment:
- `SUITABLE_NS` — low-voltage connection suitable (≤ 400 V)
- `SUITABLE_MS` — medium-voltage connection suitable (1–20 kV)
- `SUITABLE_HS` — high-voltage connection (> 20 kV)
- `LINE_ONLY` — line/cable only, no node
- `UNKNOWN` — voltage level not determinable
**Input:** one of `location` (lat,lon string), `latitude`+`longitude`, or `mastrNummer`.
Use `constrainToBbox` (directly from a `vnbdigital_lookup` bbox field) to restrict results to the relevant grid territory.
**Data:** © OpenStreetMap contributors, ODbL 1.0'
requestBody:
content:
application/json:
schema:
type: object
properties:
location:
type: string
description: Coordinates as "lat,lon" string (e.g. "49.481,8.432").
example: 49.481,8.432
latitude:
type: number
description: Latitude of the query centre.
example: 49.481
longitude:
type: number
description: Longitude of the query centre.
example: 8.432
mastrNummer:
type: string
description: MaStR number — coordinates resolved from local DB.
example: SEE900012345678
radiusMeters:
type: number
description: Search radius in metres (max 10 000).
default: 1000
example: 1000
infraTypes:
type: array
description: 'Filter by infrastructure type. Allowed: substation, transformer, line, cable.'
items:
type: string
example:
- substation
- transformer
voltageLevel:
type: string
description: 'Filter by voltage level: NS, MS, HS, EHS.'
example: NS
maxResults:
type: number
description: Maximum number of results.
default: 20
example: 20
constrainToBbox:
type: object
description: VNBDigital bounding box — objects outside are filtered out. Compatible with the bbox field from vnbdigital_lookup.
example:
north: 49.548
south: 49.427
east: 8.477
west: 8.298
properties:
north:
type: number
south:
type: number
east:
type: number
west:
type: number
include_geometry:
type: boolean
description: Include GeoJSON geometry for lines/cables.
default: false
example: false
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
examples:
nearestNS:
summary: Nearest NS infrastructure for a PV plant
value:
latitude: 49.481
longitude: 8.432
radiusMeters: 500
infraTypes:
- substation
- transformer
voltageLevel: NS
withBbox:
summary: Infrastructure constrained to VNB territory
value:
location: 49.481,8.432
radiusMeters: 2000
constrainToBbox:
north: 49.548
south: 49.427
east: 8.477
west: 8.298
cablesByMastrNummer:
summary: Lines/cables within 3 km via MaStR number
value:
mastrNummer: SEE900012345678
radiusMeters: 3000
infraTypes:
- line
- cable
include_geometry: true
/api/osm-geo/substation-finder:
post:
summary: Substation inventory for a grid territory or area
tags:
- OSM Geo (OpenStreetMap)
operationId: osm_geo_substationFinder
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Substation inventory retrieved successfully
content:
application/json:
example:
success: true
data:
query:
scopeSource: boundingBox
gridOperator: STROMDAO Netze GmbH
bbox:
- 8.298
- 49.427
- 8.477
- 49.548
voltageLevel: ALL
substationType: ALL
summary:
totalSubstations: 312
returnedSubstations: 200
byVoltageLevel:
NS_MS: 289
MS_HS: 21
HS_EHS: 2
UNKNOWN: 0
byOperator:
- operator: STROMDAO
count: 287
share: 0.92
- operator: Stadtwerke Ludwigshafen
count: 14
share: 0.04
dominantOperator: STROMDAO
dominantOperatorShare: 0.92
areaKm2: 85.4
densityAssessment:
substationsPerKm2: 3.65
label: URBAN
substations:
- osmId: way/987654321
type: substation
subtype: distribution
location:
lat: 49.487
lon: 8.451
voltageLevel: NS
operator: STROMDAO
name: TUS Oggersheim
dataQuality:
coverageLabel: MEDIUM
disclaimer: © OpenStreetMap contributors (ODbL 1.0)
description: 'Inventories substations and transformers within a defined area using OpenStreetMap data.
Returns both a detail list and **aggregated statistics**:
- Total count by voltage level (NS/MS/HS/EHS)
- Operator split with dominant operator share
- Area density assessment: `SPARSE` 5 substations/km²
**Scope input:** at least one of `location` (place name), `boundingBox` (from vnbdigital_lookup), or `gridOperator` name.
**Data:** © OpenStreetMap contributors, ODbL 1.0'
requestBody:
content:
application/json:
schema:
type: object
properties:
location:
type: string
description: Area name (Gemeinde, Stadt, Landkreis) for OSM area query.
example: Ludwigshafen am Rhein
postalCode:
type: string
description: German PLZ (postal code). Combined with location when both are provided (e.g. "74909 Meckesheim"). Can be used alone for PLZ-scoped queries.
example: '74909'
boundingBox:
type: object
description: Geographic bounding box — directly compatible with the bbox field from vnbdigital_lookup.
example:
north: 49.548
south: 49.427
east: 8.477
west: 8.298
properties:
north:
type: number
south:
type: number
east:
type: number
west:
type: number
gridOperator:
type: string
description: VNB name — used as OSM area name fallback.
example: STROMDAO Netze GmbH
gridOperatorId:
type: string
description: MaStR VNB ID (SNB…).
example: SNB935578300972
voltageLevel:
type: string
description: 'Filter by voltage level: NS, MS, HS, EHS.'
example: MS
substationType:
type: string
description: 'Filter by substation type: distribution, transmission, ALL.'
default: ALL
example: ALL
maxResults:
type: number
description: Maximum number of objects in the detail list.
default: 200
example: 200
include_geometry:
type: boolean
description: Include polygon geometry for way/relation substations.
default: false
example: false
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
examples:
byBbox:
summary: All substations in a VNB territory (via bbox)
value:
boundingBox:
north: 49.548
south: 49.427
east: 8.477
west: 8.298
gridOperator: STROMDAO Netze GmbH
hsMunich:
summary: HS substations in Munich only
value:
location: München
voltageLevel: HS
substationType: transmission
countyWithGeometry:
summary: Full county inventory with polygon geometry
value:
location: Rhein-Pfalz-Kreis
include_geometry: true
maxResults: 500
narrowLocality:
summary: Narrow locality query with PLZ (Meckesheim)
value:
location: Meckesheim
postalCode: '74909'
/api/osm-geo/grid-topology:
post:
summary: Grid topology analysis (nodes, edges, graph metrics, optional path analysis)
tags:
- OSM Geo (OpenStreetMap)
operationId: osm_geo_gridTopology
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Topology analysis returned successfully
content:
application/json:
example:
success: true
data:
area: Ludwigshafen am Rhein
scopeSource: location_name
voltageFilter: null
topologyMetrics:
nodes: 8
edges: 6
avgNodeDegree: 1.5
topologyType: RADIAL
topologyIndicator: 0
voltageBreakdown:
NS:
nodes: 0
edges: 0
lineLengthKmApprox: 0
MS:
nodes: 0
edges: 0
lineLengthKmApprox: 0
HS:
nodes: 0
edges: 0
lineLengthKmApprox: 0
EHS:
nodes: 0
edges: 0
lineLengthKmApprox: 0
UNKNOWN:
nodes: 8
edges: 6
lineLengthKmApprox: 12.4
pathAnalysis:
requested: false
dataQuality:
source: © OpenStreetMap contributors (ODbL 1.0)
coverageLabel: DERIVED
disclaimer: OSM-Daten sind freiwillig gepflegt und können unvollständig oder veraltet sein.
description: '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.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'
requestBody:
content:
application/json:
schema:
type: object
properties:
location:
type: string
description: Area name (Gemeinde, Stadt, Landkreis).
example: Ludwigshafen am Rhein
postalCode:
type: string
description: German PLZ (postal code). Combined with location when both are provided (e.g. "74909 Meckesheim"). Can be used alone for PLZ-scoped queries.
example: '74909'
boundingBox:
type: object
description: Explicit geographic bounding box — directly compatible with vnbdigital_lookup bbox.
example:
north: 49.548
south: 49.427
east: 8.477
west: 8.298
properties:
north:
type: number
south:
type: number
east:
type: number
west:
type: number
gridOperator:
type: string
description: VNB name — used as OSM area name.
example: STROMDAO Netze GmbH
voltageLevel:
type: string
description: 'Restrict analysis to one voltage level: NS, MS, HS, EHS.'
example: MS
fromOsmId:
type: string
description: Start-node OSM ID for path analysis (e.g. "node/1234567").
example: node/123456789
toOsmId:
type: string
description: Target-node OSM ID for path analysis.
example: node/987654321
includePathAnalysis:
type: boolean
description: Compute shortest path between fromOsmId → toOsmId.
default: false
example: false
includeGraphData:
type: boolean
description: Include raw node/edge list for downstream processing.
default: false
example: false
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
examples:
ludwigshafenMS:
summary: MS topology for Ludwigshafen
value:
location: Ludwigshafen am Rhein
voltageLevel: MS
pathAnalysis:
summary: Path analysis between two OSM nodes
value:
location: Ludwigshafen am Rhein
voltageLevel: MS
fromOsmId: node/123456789
toOsmId: node/987654321
includePathAnalysis: true
byBboxWithGraphData:
summary: Topology with raw graph data via bounding box
value:
boundingBox:
north: 49.548
south: 49.427
east: 8.477
west: 8.298
voltageLevel: MS
includeGraphData: true
narrowLocality:
summary: Narrow locality topology (Meckesheim / 74909)
value:
location: Meckesheim
postalCode: '74909'
includePathAnalysis: false
includeGraphData: false
/api/osm-geo/landuse-areas:
post:
summary: OSM landuse areas (residential/commercial/retail/industrial/institutional)
tags:
- OSM Geo (OpenStreetMap)
operationId: osm_geo_landuseAreas
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Landuse areas and per-type summary
content:
application/json:
example:
success: true
data:
areas:
- osmId: way/28300155
landuseType: industrial
name: Hägebüch
areaM2Approx: 123456
centroid:
lat: 49.33
lon: 8.55
summary:
totalAreaM2ByType:
industrial: 850000
commercial: 210000
retail: 95000
areaCount: 59
dataQuality:
source: © OpenStreetMap contributors (ODbL 1.0)
disclaimer: OSM-Daten sind freiwillig gepflegt und können unvollständig oder veraltet sein.
description: Fetches OSM `landuse=*` way polygons within an area and computes their area (shoelace formula on a local planar projection) and centroid locally — no external MCP dependency, same Overpass data source as osm-geo.gridTopology. Intended as sector-split evidence for municipal load/consumption estimation (area share by landuse type instead of equal distribution across a municipality). **Scope limitation:** only simple closed way polygons are handled — multipolygon relations (areas with excluded inner holes) are not fetched in v1, which understates totals for whichever areas happen to be relation-mapped rather than miscalculating them. **Scope input:** at least one of `location`, `postalCode`, or `boundingBox`.
requestBody:
content:
application/json:
schema:
type: object
properties:
location:
type: string
example: Hockenheim
postalCode:
type: string
example: '68766'
boundingBox:
type: object
example:
south: 49.273
west: 8.483
north: 49.363
east: 8.621
properties:
north:
type: number
south:
type: number
east:
type: number
west:
type: number
landuseTypes:
type: array
items:
type: string
enum:
- residential
- commercial
- retail
- industrial
- institutional
example:
- industrial
- commercial
- retail
description: 'Restrict to these landuse types (default: all 5 supported).'
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
examples:
hockenheimIndustrial:
summary: Industrial/commercial/retail areas for Hockenheim
value:
boundingBox:
south: 49.273
west: 8.483
north: 49.363
east: 8.621
landuseTypes:
- industrial
- commercial
- retail
components:
parameters:
TokenQuery:
name: token
in: query
required: false
schema:
type: string
description: Optional Cernion MCP token as URL query parameter. If provided, it overrides CERNION_TOKEN for this request. Prefer Authorization Bearer header in production to reduce token exposure in URLs/logs.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Optional Cernion MCP token. If not provided, falls back to CERNION_TOKEN from environment. Request token at https://cernion.de/ or by email: dev@stromdao.com.'