Cernion Residual Load API

openapi: 3.2.0
info:
  title: Cernion Energy Tools Residual Load 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: Residual Load
paths:
  /api/residual-load/net-residual-load:
    post:
      summary: Net residual load forecast (SMARD load − MaStR EE generation)
      tags:
      - Residual Load
      operationId: residual_load_netResidualLoad
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Residual load forecast generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      region:
                        type: string
                        example: Ludwigshafen
                      isHistorical:
                        type: boolean
                        description: true when startDate is in the past (SMARD filter 410 + observed weather used)
                        example: false
                      dataMode:
                        type: string
                        enum:
                        - weather_forecast
                        - historical_observation
                        description: '"weather_forecast" for future dates, "historical_observation" for past dates'
                        example: weather_forecast
                      forecastPeriod:
                        type: object
                        properties:
                          start:
                            type: string
                            format: date-time
                          end:
                            type: string
                            format: date-time
                      resolution:
                        type: string
                        example: hourly
                      dataPoints:
                        type: number
                        example: 24
                      installedCapacity:
                        type: object
                        properties:
                          totalPV_MW:
                            type: number
                            example: 42.7
                          totalWind_MW:
                            type: number
                            example: 8.1
                          pvInstallations:
                            type: number
                            example: 1203
                          windInstallations:
                            type: number
                            example: 12
                      loadScaling:
                        type: object
                        properties:
                          populationUsed:
                            type: string
                            example: '170.000'
                          scalingFactorPct:
                            type: string
                            example: 0.202%
                          isActualData:
                            type: boolean
                            example: true
                          dataSource:
                            type: string
                            example: SMARD filter 410 (realized)
                      kpis:
                        type: object
                        properties:
                          peakResidualLoadMW:
                            type: number
                            example: 87.4
                          peakResidualAt:
                            type: string
                            format: date-time
                          minResidualLoadMW:
                            type: number
                            example: 31.2
                          avgResidualLoadMW:
                            type: number
                            example: 58.9
                          totalLoadMWh:
                            type: number
                            example: 1413.6
                          totalEEGenerationMWh:
                            type: number
                            example: 38.2
                          totalResidualLoadMWh:
                            type: number
                            example: 1375.4
                          avgEESharePct:
                            type: number
                            example: 2.7
                  forecast:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          format: date-time
                        loadMW:
                          type: number
                          description: Regional load in MW
                        pvGenerationMW:
                          type: number
                          description: PV generation in MW
                        windGenerationMW:
                          type: number
                          description: Wind generation in MW
                        eeGenerationMW:
                          type: number
                          description: Total EE generation in MW
                        residualLoadMW:
                          type: number
                          description: Net residual load in MW (= loadMW − eeGenerationMW)
                        eeSharePct:
                          type: number
                          description: EE share of total load in %
                  methodology:
                    type: object
                    properties:
                      loadModel:
                        type: string
                      eeModel:
                        type: string
                      residualFormula:
                        type: string
                        example: Residuallast = RegionaleLast − PV − Wind
                      interpolation:
                        type: string
            text/csv:
              description: CSV with metadata comments (when format=csv)
              example: '# Net Residual Load Forecast

                # Region: Ludwigshafen

                Timestamp,Load (MW),PV Generation (MW),Wind Generation (MW),EE Generation (MW),Residual Load (MW),EE Share (%)'
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              description: Excel XLSX with Forecast + Summary sheets (when format=xlsx)
              schema:
                type: string
                format: binary
        '400':
          description: Invalid request parameters
          content:
            application/json:
              example:
                success: false
                error:
                  code: RESIDUAL_LOAD_ERROR
                  message: region is required
      description: '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'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                region:
                  type: string
                  description: City or region name for SMARD population scaling (e.g. "Ludwigshafen", "Bayern", "Heidelberg")
                  example: Ludwigshafen
                gridOperatorMastrId:
                  type: string
                  description: MaStR Netzbetreiber-ID (SNB/GNB...) for EE capacity query. Resolve via cernion_vnb_lookup.
                  example: SNB935578300972
                bundesland:
                  type: string
                  description: Federal state
                  example: Rheinland-Pfalz
                landkreis:
                  type: string
                  description: Landkreis name
                  example: Ludwigshafen am Rhein
                gemeinde:
                  type: string
                  description: Municipality name
                  example: Ludwigshafen
                postleitzahl:
                  type: string
                  pattern: ^[0-9]{5}$
                  description: 5-digit postal code
                  example: '67059'
                latitude:
                  type: number
                  description: Latitude for weather data
                  example: 49.4744
                longitude:
                  type: number
                  description: Longitude for weather data
                  example: 8.4349
                populationOverride:
                  type: number
                  description: Known population of the grid area. Overrides internal lookup. Important for industrial locations (e.g. BASF/Ludwigshafen).
                  example: 170000
                forecastDays:
                  type: number
                  minimum: 1
                  maximum: 14
                  default: 1
                  description: Number of forecast days (1–14)
                  example: 1
                resolution:
                  type: string
                  enum:
                  - hourly
                  - hour
                  - 15min
                  default: hourly
                  description: '`"hourly"` / `"hour"` = 24 pts/day (trading); `"15min"` = 96 pts/day (§12 StromNZV Fahrplan). `"hour"` is accepted as an alias for `"hourly"`.'
                  example: hourly
                installationType:
                  type: string
                  enum:
                  - solar
                  - wind
                  - all
                  default: all
                  description: Which EE types to subtract from load
                  example: all
                startDate:
                  type: string
                  pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
                  description: '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.'
                  example: '2026-02-10'
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  - xlsx
                  default: json
                  description: Output format
                  example: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              dayAheadProcurement:
                summary: STROMDAO day-ahead procurement (15-min, tomorrow)
                value:
                  region: Ludwigshafen
                  gridOperatorMastrId: SNB935578300972
                  forecastDays: 1
                  resolution: 15min
                  installationType: all
              weeklyBavaria:
                summary: Weekly residual load for Bavaria (hourly)
                value:
                  region: Bayern
                  bundesland: Bayern
                  forecastDays: 7
                  resolution: hourly
              industrialSite:
                summary: Industrial site with known population override
                value:
                  region: Mannheim
                  populationOverride: 320000
                  forecastDays: 2
                  resolution: 15min
              csvExport:
                summary: Download residual load profile as CSV
                value:
                  region: Heidelberg
                  postleitzahl: '69115'
                  forecastDays: 1
                  resolution: hourly
                  format: csv
              xlsxExport:
                summary: Download residual load profile as Excel
                value:
                  region: Bayern
                  bundesland: Bayern
                  forecastDays: 3
                  resolution: 15min
                  format: xlsx
              historicalResidualLoad:
                summary: Historical residual load analysis (past date, realised SMARD data)
                value:
                  region: Ludwigshafen
                  gridOperatorMastrId: SNB935578300972
                  startDate: '2026-02-10'
                  forecastDays: 7
                  resolution: hourly
  /api/residual-load/load-forecast-regional:
    post:
      summary: Regional load forecast with LLM reasoning and real MaStR capacity anchors
      tags:
      - Residual Load
      operationId: residual_load_loadForecastRegional
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Load forecast generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    description: LLM-generated load forecast analysis with real MaStR capacity anchors
      description: 'LLM-based regional load forecast enriched with **real MaStR installation data** injected into the reasoning prompt.


        **What is real vs. LLM-estimated:**

        | Component | Data source |

        |-----------|-------------|

        | Installed PV capacity (MW, installation count) | MaStR (real) |

        | Installed wind capacity (MW, installation count) | MaStR (real) |

        | SMARD population scaling factor | SMARD.de (real) |

        | Load profile shape, calendar effects, procurement recommendation | LLM reasoning |


        **Graceful degradation:** If MaStR queries time out, the tool falls back to placeholder values and the LLM call still completes.


        **Use cases:**

        - Stadtwerk procurement planning with natural-language recommendations

        - KPI summaries for management dashboards

        - When full hour-by-hour time-series (see `netResidualLoad`) is not needed'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                region:
                  type: string
                  description: City or region name
                  example: Mannheim
                forecastDays:
                  type: number
                  minimum: 1
                  maximum: 7
                  default: 1
                  description: Number of days to forecast (1–7)
                  example: 1
                populationOverride:
                  type: number
                  description: Known population of the grid area. Improves load scaling accuracy.
                  example: 320000
                gridOperatorMastrId:
                  type: string
                  description: MaStR Netzbetreiber-ID for EE capacity lookup
                  example: SNB935578300972
                bundesland:
                  type: string
                  description: Federal state for MaStR capacity query
                  example: Baden-Württemberg
                postleitzahl:
                  type: string
                  description: 5-digit postal code for MaStR capacity query
                  example: '68159'
                additionalContext:
                  type: string
                  description: Extra context for the LLM (e.g. "large BASF industrial plant in area")
                  example: Large chemical plant (BASF) adds ~200 MW industrial base load
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              dayAheadMannheim:
                summary: Day-ahead load forecast for Mannheim
                value:
                  region: Mannheim
                  populationOverride: 320000
                  forecastDays: 1
              weeklyWithOperator:
                summary: 3-day forecast for a grid operator area
                value:
                  region: Ludwigshafen
                  gridOperatorMastrId: SNB935578300972
                  forecastDays: 3
              industrialContext:
                summary: Industrial site with additional LLM context
                value:
                  region: Ludwigshafen
                  populationOverride: 170000
                  additionalContext: Large chemical plant (BASF) adds ~200 MW industrial base load
                  forecastDays: 1
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.'