Cernion German Grid Data API

openapi: 3.2.0
info:
  title: Cernion Energy Tools German Grid Data 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: German Grid Data
paths:
  /api/german-grid/spotprices:
    post:
      summary: German spotmarket prices (EPEX/EEX) for dynamic tariffs
      tags:
      - German Grid Data
      operationId: german_grid_spotprices
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Spot price data retrieved successfully
          content:
            application/json:
              schema:
                type: object
            text/csv:
              description: CSV download (when format=csv)
              schema:
                type: string
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              description: Excel XLSX download (when format=xlsx or format=xls)
              schema:
                type: string
                format: binary
      description: 'Official data from Netztransparenz.de, OAuth2 authenticated. **Automatic ENTSO-E fallback**: when Netztransparenz.de has no data or returns an API error (e.g. for recent/future dates), the endpoint transparently retries with ENTSO-E day-ahead prices (hourly, DE bidding zone). The response is annotated with `data.fallback: true` and `data.fallbackSource: "entsoe_day_ahead_prices"` when the fallback is used.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dateFrom
              - dateTo
              properties:
                dateFrom:
                  type: string
                  description: 'Start date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today
                dateTo:
                  type: string
                  description: 'End date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today
                includeStatistics:
                  type: boolean
                  description: Include price statistics (min/max/avg)
                  default: true
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  - xlsx
                  - xls
                  description: Output format. "csv" and "xls"/"xlsx" trigger a file download.
                  default: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              weekPrices:
                summary: Week of spot prices
                value:
                  dateFrom: '2026-02-01'
                  dateTo: '2026-02-07'
                  includeStatistics: true
              monthPrices:
                summary: Full month analysis
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-01-31'
                  includeStatistics: true
              singleDay:
                summary: Single day prices
                value:
                  dateFrom: '2026-02-01'
                  dateTo: '2026-02-01'
                  includeStatistics: false
              relativeAlias:
                summary: Today's prices using relative date alias
                value:
                  dateFrom: today
                  dateTo: today
                  includeStatistics: true
              recentWeek:
                summary: Last 7 days using relative aliases
                value:
                  dateFrom: today-6
                  dateTo: today
                  includeStatistics: true
                  format: csv
              csvExport:
                summary: Export spot prices as CSV
                value:
                  dateFrom: '2026-02-01'
                  dateTo: '2026-02-07'
                  format: csv
  /api/german-grid/negative-prices:
    post:
      summary: Negative price analysis for §51 EEG 2023 compliance
      tags:
      - German Grid Data
      operationId: german_grid_negativePrices
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Negative price analysis retrieved successfully
          content:
            application/json:
              schema:
                type: object
            text/csv:
              description: CSV download (when format=csv)
              schema:
                type: string
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              description: Excel XLSX download (when format=xlsx or format=xls)
              schema:
                type: string
                format: binary
      description: 'Analyze negative price periods for EEG direct marketing compliance and prosumer advisory. **Critical for §51 EEG 2023 compliance.**


        **§51 EEG 2023 Regulation**:

        - **No compensation** during ≥6 consecutive hours of negative spot prices

        - Applies to: EEG direct marketing (Direktvermarktung)

        - Affects: Installations in direct marketing, prosumers considering switch

        - Penalty: Zero compensation for entire negative price period (can be €100-500+ loss per event)


        **Logic Parameter (consecutive hours)**:

        - **1 hour**: Any negative price (strictest - for sensitivity analysis)

        - **4 hours**: Pre-warning threshold (monitor market conditions)

        - **6 hours** (**DEFAULT**): §51 EEG 2023 legal threshold

        - **15 hours**: Extreme events only (rare, 20 events/year = risky**


        3. **Risk Management** (energy suppliers)

        - Identify high-risk months (typically: Mar-Apr, Oct-Nov = high wind + low demand)

        - Portfolio exposure: Total installed capacity × negative price hours

        - Hedge strategies: Battery storage, demand response, curtailment agreements


        4. **Market Analysis**:

        - Negative price frequency trends (increasing = more renewables, more risk)

        - Seasonal patterns (spring/fall = highest risk due to wind + low demand)

        - Geographic differences (northern Germany = more wind = more negative prices)


        **Typical Negative Price Events** (Germany):

        - **Frequency**: 10-30 events/year (≥6 consecutive hours)

        - **Seasons**: Spring (Mar-May) and Fall (Sep-Nov) highest risk

        - **Causes**: High renewable generation + low demand + limited export capacity

        - **Duration**: Typically 6-12 hours, occasionally up to 24 hours

        - **Price range**: -50 to -200 €/MWh (extreme: -500 €/MWh)


        **Financial Impact Example**:

        - 100 kWp installation in direct marketing

        - 15 negative price events/year × 8 hours avg × 100 kW × 100 €/MWh market price

        - **Potential loss: 12,000 €/year** if not managed

        - Mitigation: Self-consumption during negative prices (reduces loss to ~3,000 €/year)


        **Best Practices**:

        - Monitor monthly (identify trends early)

        - Advise prosumers: Direct marketing only if 30 kWp capacity

        - Include negative price risk in direct marketing contracts

        - Combine with §14a EnWG controllable devices (reduce grid impact during negative prices)'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dateFrom
              - dateTo
              properties:
                dateFrom:
                  type: string
                  description: 'Start date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today-30
                dateTo:
                  type: string
                  description: 'End date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today
                logic:
                  type: number
                  enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 6
                  - 15
                  description: Consecutive hours threshold (§51 EEG 2023 uses 6)
                  default: 6
                includeEegCompliance:
                  type: boolean
                  description: Include EEG compliance analysis
                  default: true
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  - xlsx
                  - xls
                  description: Output format. "csv" and "xls"/"xlsx" trigger a file download.
                  default: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              eegCompliance:
                summary: §51 EEG 2023 compliance check (6h threshold)
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-01-31'
                  logic: 6
                  includeEegCompliance: true
              quarterAnalysis:
                summary: Q1 negative price analysis
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-03-31'
                  logic: 6
                  includeEegCompliance: true
              customThreshold:
                summary: Custom 4-hour threshold
                value:
                  dateFrom: '2026-02-01'
                  dateTo: '2026-02-28'
                  logic: 4
              relativeAlias:
                summary: Last 30 days using relative date alias
                value:
                  dateFrom: today-30
                  dateTo: today
                  logic: 6
                  includeEegCompliance: true
              csvExport:
                summary: Export negative price periods as CSV (Power Automate)
                value:
                  dateFrom: today-30
                  dateTo: today
                  logic: 6
                  includeEegCompliance: true
                  format: csv
  /api/german-grid/forecast:
    post:
      summary: Solar/wind generation forecasts for grid planning and load forecasting
      tags:
      - German Grid Data
      operationId: german_grid_forecast
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Generation forecast data retrieved successfully
          content:
            application/json:
              schema:
                type: object
            text/csv:
              description: CSV download (when format=csv)
              schema:
                type: string
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              description: Excel XLSX download (when format=xlsx or format=xls)
              schema:
                type: string
                format: binary
      description: Official forecasts from German transmission system operators
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - product
              - dateFrom
              - dateTo
              properties:
                product:
                  type: string
                  enum:
                  - Solar
                  - Wind
                  description: Renewable energy type to forecast
                  example: Solar
                dateFrom:
                  type: string
                  description: 'Start date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: tomorrow
                dateTo:
                  type: string
                  description: 'End date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today+6
                includeActual:
                  type: boolean
                  description: Include actual generation data for comparison
                  default: false
                includeOnline:
                  type: boolean
                  description: Include online capacity data
                  default: false
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  - xlsx
                  - xls
                  description: Output format. "csv" and "xls"/"xlsx" trigger a file download.
                  default: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              solarWeekForecast:
                summary: Solar generation forecast (1 week)
                value:
                  product: Solar
                  dateFrom: '2026-02-08'
                  dateTo: '2026-02-14'
                  includeActual: false
                  includeOnline: true
              windMonthWithActual:
                summary: Wind forecast + actual comparison
                value:
                  product: Wind
                  dateFrom: '2026-01-01'
                  dateTo: '2026-01-31'
                  includeActual: true
                  includeOnline: true
              solarDayAhead:
                summary: Solar day-ahead forecast
                value:
                  product: Solar
                  dateFrom: '2026-02-08'
                  dateTo: '2026-02-08'
                  includeOnline: false
              relativeAlias:
                summary: Solar forecast for next 7 days using relative aliases
                value:
                  product: Solar
                  dateFrom: tomorrow
                  dateTo: today+7
                  includeOnline: true
              csvExport:
                summary: Export forecast as CSV
                value:
                  product: Solar
                  dateFrom: '2026-02-08'
                  dateTo: '2026-02-14'
                  format: csv
  /api/german-grid/redispatch:
    post:
      summary: Redispatch measures and grid congestion analysis
      tags:
      - German Grid Data
      operationId: german_grid_redispatch
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Redispatch data retrieved successfully
          content:
            application/json:
              schema:
                type: object
            text/csv:
              description: CSV download (when format=csv)
              schema:
                type: string
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              description: Excel XLSX download (when format=xlsx or format=xls)
              schema:
                type: string
                format: binary
      description: Grid congestion analysis, curtailment risk assessment, NEST project justification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dateFrom
              - dateTo
              properties:
                dateFrom:
                  type: string
                  description: 'Start date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today-30
                dateTo:
                  type: string
                  description: 'End date. ISO format (YYYY-MM-DD) or relative alias: `today`, `today+N`, `today-N`, `tomorrow`, `yesterday`.'
                  example: today
                includeAnalysis:
                  type: boolean
                  description: Include congestion analysis
                  default: true
                includeCurtailment:
                  type: boolean
                  description: Include curtailment data
                  default: false
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  - xlsx
                  - xls
                  description: Output format. "csv" and "xls"/"xlsx" trigger a file download.
                  default: json
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              monthlyAnalysis:
                summary: Monthly redispatch analysis
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-01-31'
                  includeAnalysis: true
                  includeCurtailment: true
              quarterOverview:
                summary: Q1 congestion overview
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-03-31'
                  includeAnalysis: true
                  includeCurtailment: false
              weekCurtailment:
                summary: Weekly curtailment analysis
                value:
                  dateFrom: '2026-02-01'
                  dateTo: '2026-02-07'
                  includeCurtailment: true
              relativeAlias:
                summary: Last 30 days using relative date alias
                value:
                  dateFrom: today-30
                  dateTo: today
                  includeAnalysis: true
                  includeCurtailment: true
              csvExport:
                summary: Export redispatch data as CSV
                value:
                  dateFrom: '2026-01-01'
                  dateTo: '2026-01-31'
                  format: csv
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.'