Residual Load

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

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:

PeriodSourceisActualData
Past/todayFilter 410 (realised, ~1h delay)true
D+1Filter 411 (day-ahead TSO forecast)true
D+2–D+14Filter 410, reference week −7 daysfalse

⚠️ 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
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

Query parameters

tokenstring

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.

Request body

regionstring

City or region name for SMARD population scaling (e.g. "Ludwigshafen", "Bayern", "Heidelberg")

gridOperatorMastrIdstring

MaStR Netzbetreiber-ID (SNB/GNB...) for EE capacity query. Resolve via cernion_vnb_lookup.

bundeslandstring

Federal state

landkreisstring

Landkreis name

gemeindestring

Municipality name

postleitzahlstring

5-digit postal code

latitudenumber

Latitude for weather data

longitudenumber

Longitude for weather data

populationOverridenumber

Known population of the grid area. Overrides internal lookup. Important for industrial locations (e.g. BASF/Ludwigshafen).

forecastDaysnumber

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

startDatestring

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

tokenstring

Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

Example request

{
  "region": "Ludwigshafen",
  "gridOperatorMastrId": "SNB935578300972",
  "bundesland": "Rheinland-Pfalz",
  "landkreis": "Ludwigshafen am Rhein",
  "gemeinde": "Ludwigshafen",
  "postleitzahl": "67059",
  "latitude": 49.4744,
  "longitude": 8.4349,
  "populationOverride": 170000,
  "forecastDays": 1,
  "resolution": "hourly",
  "installationType": "all",
  "startDate": "2026-02-10",
  "format": "json"
}

Response

Residual load forecast generated successfully

Example response

{
  "summary": {
    "region": "Ludwigshafen",
    "dataMode": "weather_forecast",
    "resolution": "hourly",
    "dataPoints": 24,
    "installedCapacity": {
      "totalPV_MW": 42.7,
      "totalWind_MW": 8.1,
      "pvInstallations": 1203,
      "windInstallations": 12
    },
    "loadScaling": {
      "populationUsed": "170.000",
      "scalingFactorPct": "0.202%",
      "isActualData": true,
      "dataSource": "SMARD filter 410 (realized)"
    },
    "kpis": {
      "peakResidualLoadMW": 87.4,
      "minResidualLoadMW": 31.2,
      "avgResidualLoadMW": 58.9,
      "totalLoadMWh": 1413.6,
      "totalEEGenerationMWh": 38.2,
      "totalResidualLoadMWh": 1375.4,
      "avgEESharePct": 2.7
    }
  },
  "methodology": {
    "residualFormula": "Residuallast = RegionaleLast − PV − Wind"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.