openapi: 3.0.3
info:
  title: aWATTar Market Data API
  description: RESTful API providing hourly EPEX Spot electricity market prices for Austria and Germany. Returns JSON data with start/end timestamps and market price in EUR/MWh. Supports optional start and end parameters (epoch milliseconds) to filter the time range. No authentication required. Updated daily at 14:00 CET for the next 24 hours. Available for both Austria (api.awattar.at) and Germany (api.awattar.de).
  version: 1.0.0
  contact:
    url: https://www.awattar.at/services/api
  license:
    name: Fair Use
    url: https://www.awattar.at/services/api
servers:
- url: https://api.awattar.at
  description: Austria endpoint
- url: https://api.awattar.de
  description: Germany endpoint
tags:
- name: Market Data
  description: EPEX Spot electricity market price data
paths:
  /v1/marketdata:
    get:
      summary: Get hourly electricity market prices
      description: Returns a list of hourly EPEX Spot electricity market prices. Prices are updated daily at 14:00 CET covering the following 24-hour period. If no time range is specified, the current day's available data is returned. The API is free to use under a fair-use policy of 100 requests per day per client.
      operationId: getMarketData
      tags:
      - Market Data
      parameters:
      - name: start
        in: query
        description: Start of the requested time range as Unix epoch timestamp in milliseconds. If omitted, defaults to the beginning of the current available data window.
        required: false
        schema:
          type: integer
          format: int64
          example: 1428591600000
      - name: end
        in: query
        description: End of the requested time range as Unix epoch timestamp in milliseconds. If omitted, defaults to the end of the current available data window.
        required: false
        schema:
          type: integer
          format: int64
          example: 1428678000000
      responses:
        '200':
          description: Successful response with a list of hourly market price entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketDataResponse'
              examples:
                sample:
                  $ref: '#/components/examples/MarketDataSample'
        '400':
          description: Bad request - invalid parameter values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - fair-use limit of 100 requests per day per client exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    MarketPriceEntry:
      type: object
      description: A single hourly electricity market price data point
      properties:
        start_timestamp:
          type: integer
          format: int64
          description: Start of the pricing interval as Unix epoch timestamp in milliseconds (UTC)
          example: 1428591600000
        end_timestamp:
          type: integer
          format: int64
          description: End of the pricing interval as Unix epoch timestamp in milliseconds (UTC). Typically 3600000 ms (1 hour) after start_timestamp.
          example: 1428595200000
        marketprice:
          type: number
          format: double
          description: EPEX Spot market price for the interval in EUR/MWh. Can be negative during periods of excess renewable energy supply.
          example: 42.09
        unit:
          type: string
          description: Unit of measurement for the market price
          example: Eur/MWh
          enum:
          - Eur/MWh
      required:
      - start_timestamp
      - end_timestamp
      - marketprice
      - unit
    MarketDataResponse:
      type: object
      description: A paginated list of hourly electricity market price entries
      properties:
        object:
          type: string
          description: Type identifier for the response object
          example: list
          enum:
          - list
        data:
          type: array
          description: Array of hourly market price entries
          items:
            $ref: '#/components/schemas/MarketPriceEntry'
      required:
      - object
      - data
    ErrorResponse:
      type: object
      description: Error response returned when a request cannot be fulfilled
      properties:
        error:
          type: string
          description: Machine-readable error code
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable description of the error
          example: Fair-use limit of 100 requests per day exceeded
  examples:
    MarketDataSample:
      summary: Sample market data response with 3 hourly entries
      value:
        object: list
        data:
        - start_timestamp: 1428591600000
          end_timestamp: 1428595200000
          marketprice: 42.09
          unit: Eur/MWh
        - start_timestamp: 1428595200000
          end_timestamp: 1428598800000
          marketprice: 38.5
          unit: Eur/MWh
        - start_timestamp: 1428598800000
          end_timestamp: 1428602400000
          marketprice: -5.12
          unit: Eur/MWh
externalDocs:
  description: aWATTar API Documentation
  url: https://www.awattar.at/services/api