---
title: "Net residual load forecast (SMARD load − MaStR EE generation)"
method: POST
path: "/api/residual-load/net-residual-load"
tags: ["Residual Load"]
---

# Net residual load forecast (SMARD load − MaStR EE generation)

`POST /api/residual-load/net-residual-load`

## Request

- Base URL: `https://api.cernion.de`
- URL: `https://api.cernion.de/api/residual-load/net-residual-load`
- Auth: none declared

Calculates **net residual load** for a grid area or region — the electricity volume a Stadtwerk or EVU must procure on the EPEX spot market:

**Residual Load = Regional Load − PV Generation − Wind Generation**

**Data sources (all real API data, no LLM estimates):**
- **Regional load**: SMARD.de national load × population ratio (no API key required)
- **PV generation**: MaStR installed capacity × IEC 61853 solar model + Visual Crossing weather
- **Wind generation**: MaStR installed capacity × IEC 61400 wind model + Visual Crossing weather

**Time resolutions:**
- `"hourly"` (default): 24 data points/day — intraday dispatch planning, trading
- `"15min"`: 96 data points/day — §12 StromNZV Fahrplanlieferung and Bilanzkreisabrechnung

**SMARD data availability:**
| Period | Source | isActualData |
|--------|--------|--------------|
| Past/today | Filter 410 (realised, ~1h delay) | true |
| D+1 | Filter 411 (day-ahead TSO forecast) | true |
| D+2–D+14 | Filter 410, reference week −7 days | false |

**⚠️ Known limitations:**
- Load is approximated via population ratio — good for residential/SME, not large industrial consumers
- Use `populationOverride` for known population figures (improves scaling accuracy)
- EE accuracy ±10–20 % depending on weather forecast quality (degrades D+3 and beyond)
**Historical mode (`startDate` in the past):**
- SMARD automatically switches to filter 410 (realised load, no extra parameter needed)
- Visual Crossing returns observed weather instead of a forecast — identical IEC calculation
- Response gains `summary.isHistorical: true` and `summary.dataMode: "historical_observation"`
- Historical responses are cached for **30 days** (immutable data, no additional API quota)
**Use cases:**
- **Day-ahead procurement**: Determine how much to buy on EPEX (residual load = required purchase)
- **Intraday management**: Hourly/15-min profile for dispatch optimisation
- **Grid planning**: Identify peak residual load periods for capacity planning
- **Billing groups (§12 StromNZV)**: 15-min Fahrplan delivery to TSO/DSO

## Query parameters

- `token` string

## Request body

- object
  - `region` string: City or region name for SMARD population scaling (e.g. "Ludwigshafen", "Bayern", "Heidelberg")
  - `gridOperatorMastrId` string: MaStR Netzbetreiber-ID (SNB/GNB...) for EE capacity query. Resolve via cernion_vnb_lookup.
  - `bundesland` string: Federal state
  - `landkreis` string: Landkreis name
  - `gemeinde` string: Municipality name
  - `postleitzahl` string: 5-digit postal code
  - `latitude` number: Latitude for weather data
  - `longitude` number: Longitude for weather data
  - `populationOverride` number: Known population of the grid area. Overrides internal lookup. Important for industrial locations (e.g. BASF/Ludwigshafen).
  - `forecastDays` number: Number of forecast days (1–14)
  - `resolution` 'hourly' | 'hour' | '15min': `"hourly"` / `"hour"` = 24 pts/day (trading); `"15min"` = 96 pts/day (§12 StromNZV Fahrplan). `"hour"` is accepted as an alias for `"hourly"`.
  - `installationType` 'solar' | 'wind' | 'all': Which EE types to subtract from load
  - `startDate` string: Optional start date (YYYY-MM-DD). Omit for default tomorrow behaviour. Past dates switch to historical observation mode: SMARD filter 410 (realised) + observed weather, 30-day cache.
  - `format` 'json' | 'csv' | 'xlsx': Output format
  - `token` string: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

## Response `200`

Residual load forecast generated successfully

- object
  - `summary` object
    - `region` string
    - `isHistorical` boolean: true when startDate is in the past (SMARD filter 410 + observed weather used)
    - `dataMode` 'weather_forecast' | 'historical_observation': "weather_forecast" for future dates, "historical_observation" for past dates
    - `forecastPeriod` object
      - `start` string, date-time
      - `end` string, date-time
    - `resolution` string
    - `dataPoints` number
    - `installedCapacity` object
      - `totalPV_MW` number
      - `totalWind_MW` number
      - `pvInstallations` number
      - `windInstallations` number
    - `loadScaling` object
      - `populationUsed` string
      - `scalingFactorPct` string
      - `isActualData` boolean
      - `dataSource` string
    - `kpis` object
      - `peakResidualLoadMW` number
      - `peakResidualAt` string, date-time
      - `minResidualLoadMW` number
      - `avgResidualLoadMW` number
      - `totalLoadMWh` number
      - `totalEEGenerationMWh` number
      - `totalResidualLoadMWh` number
      - `avgEESharePct` number
  - `forecast` object[]
    - `timestamp` string, date-time
    - `loadMW` number: Regional load in MW
    - `pvGenerationMW` number: PV generation in MW
    - `windGenerationMW` number: Wind generation in MW
    - `eeGenerationMW` number: Total EE generation in MW
    - `residualLoadMW` number: Net residual load in MW (= loadMW − eeGenerationMW)
    - `eeSharePct` number: EE share of total load in %
  - `methodology` object
    - `loadModel` string
    - `eeModel` string
    - `residualFormula` string
    - `interpolation` string

## Other responses

- `400`: Invalid request parameters

---

[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)