Energy Prices, CO2 Savings, and Offer Calculator API

Overview

The pricing endpoints give you access to market price data, CO2 emissions calculations, local utility benchmarks, and a full tariff offer calculator for generating customer quotes. These are read-only endpoints and do not require a contract or user context. Base URL: https://api.lumenaza.de/ · Test URL: https://api.test.lumenaza.de/

EPEX Spot Day-Ahead Prices

GET /v3/prices/epex_day_ahead/

Returns EPEX Spot day-ahead auction prices for a given time window. Prices may be negative during periods of oversupply.

Query Parameters

Parameter	Type	Required	Description
`from`	string	✅ Yes	Start of the range (ISO 8601 datetime, included).
`to`	string	✅ Yes	End of the range (ISO 8601 datetime, excluded).
`aggregation_type`	string	No	Optional aggregation bucket. One of `alltime`, `day`, `hour`, `month`, `year`.

Response

An array of price intervals:

Field	Type	Description
`start_time`	string	ISO 8601 start of the price interval.
`end_time`	string	ISO 8601 end of the price interval.
`price`	float/null	Market price for this interval (€/MWh). `null` if unavailable.

Example: 24-Hour Window

curl -X GET "https://api.lumenaza.de/v3/prices/epex_day_ahead/?from=2024-06-15T00:00:00Z&to=2024-06-16T00:00:00Z" \
  -H "Authorization: Bearer <token>"

[
  {
    "start_time": "2024-06-15T00:00:00Z",
    "end_time": "2024-06-15T01:00:00Z",
    "price": 68.42
  },
  {
    "start_time": "2024-06-15T01:00:00Z",
    "end_time": "2024-06-15T02:00:00Z",
    "price": 64.10
  },
  {
    "start_time": "2024-06-15T02:00:00Z",
    "end_time": "2024-06-15T03:00:00Z",
    "price": 59.87
  },
  {
    "start_time": "2024-06-15T12:00:00Z",
    "end_time": "2024-06-15T13:00:00Z",
    "price": -4.20
  }
]

CO2 Savings Calculation

GET /v3/prices/get_co2_savings/

Calculates the CO2 savings for a given consumption amount and year, based on the BDEW-published CO2 emission factor for the German electricity grid mix for that year.

Query Parameters

Parameter	Type	Required	Description
`consumption`	float	✅ Yes	Energy consumption in kWh.
`year`	integer	✅ Yes	Reference year for the BDEW emission factor. Valid range: `2013`–`2026`.

Response

Field	Type	Description
`saved_co2`	float	Estimated CO2 savings in grams.

Example Request

curl -X GET "https://api.lumenaza.de/v3/prices/get_co2_savings/?consumption=3500&year=2024" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "saved_co2": 1452500.0
}

Local Incumbent Utility Price

GET /v3/prices/get_local_utility_price/

Returns the current (or historical) tariff price of the incumbent local utility for a given address and consumption. This can be used to benchmark your offering against the local basic supply tariff.

Query Parameters

Parameter	Type	Required	Description
`city`	string	✅ Yes	City name for the address lookup.
`street`	string	✅ Yes	Street name (without house number).
`zipcode`	string	✅ Yes	Postal code of the address.
`consumption`	integer	✅ Yes	Annual electricity consumption in kWh. Maximum value: `100000`.
`house_number`	string	No	House number. Providing this reduces address ambiguity.
`date`	string	No	ISO 8601 date for historical price lookup. Defaults to the current date.
`is_business`	boolean	No	Set to `true` for business tariff lookup. Defaults to `false` (residential).

Response

Field	Type	Description
`local_utility_name`	string	Name of the incumbent local utility provider.
`local_utility_year_price`	float	Annual energy cost at the local utility’s tariff (€/year).

Error: Ambiguous Address

If the provided address matches more than one location, the API returns a 400 Bad Request response. Provide more specific address details (e.g., house_number) to resolve the ambiguity.

Example Request

curl -X GET "https://api.lumenaza.de/v3/prices/get_local_utility_price/?city=Berlin&street=Unter+den+Linden&zipcode=10117&house_number=1&consumption=3500" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "local_utility_name": "Vattenfall Wärme Berlin AG",
  "local_utility_year_price": 1204.50
}

Offer Calculator

GET /v3/offer_calculator/

Generates a detailed customer-facing tariff quote. The required parameters vary depending on whether you are quoting a fixed-price consumer, spot-price consumer, or producer tariff.

Common Required Parameter

Parameter	Type	Required	Description
`tariff_name`	string	✅ Yes	Internal name of the tariff to calculate the offer for.

Additional Parameters by Tariff Type

Fix price consumer tariff:

Parameter	Type	Required	Description
`zip_code`	string	✅ Yes	Customer’s postal code for grid fee calculation.
`consumption`	integer	✅ Yes	Annual consumption in kWh. Must be ≥ 1.

Spot price consumer tariff:

Parameter	Type	Required	Description
`zip_code`	string	✅ Yes	Customer’s postal code.
`months_for_average_prices_and_costs`	integer	✅ Yes	Number of past months to use when averaging spot prices and costs. Valid range: `1`–`24`.

Producer tariff:

Parameter	Type	Required	Description
`plant_type`	string	✅ Yes	Generation technology. One of `solar`, `gas`, `wind`, `water`.
`installed_capacity`	float	✅ Yes	Installed capacity of the plant in kW.
`feed_in_energy_amount`	float	✅ Yes	Expected annual feed-in volume in kWh.
`months_for_average_prices_and_costs`	integer	✅ Yes	Number of past months to use for average price and cost calculations. Valid range: `1`–`24`.

Response: TariffOutput

The response contains two sections: a per-line-item breakdown and total price summaries. offer_item_price_results — array of individual tariff components:

Field	Type	Description
`name`	string	Name of the tariff line item (e.g., “Energy Price”, “Grid Fee”).
`price_net`	float	Net price for this item.
`price_gross`	float	Gross price for this item (including VAT).
`unit`	string	Unit of the price (e.g., `ct/kWh`, `€/year`).
`item_amount`	float	Quantity or amount this price applies to.

total_price_results — summary totals:

Field	Type	Description
`ct/y`	float	Total annual cost in cents.
`ct/m`	float	Total monthly cost in cents.
`ct`	float	One-time costs in cents (if applicable).

Ambiguous Address: 300 Response

If the address cannot be uniquely resolved, the API returns an HTTP 300 Multiple Choices response. The body contains the submitted zipcode and a streets array of [street, city] pairs to choose from:

{
  "zipcode": "60313",
  "streets": [
    ["Schillerstraße", "Frankfurt am Main"],
    ["Schillerstraße", "Frankfurt an der Oder"]
  ]
}

Example Request (Fixed Price Consumer)

curl -X GET "https://api.lumenaza.de/v3/offer_calculator/?tariff_name=lumenaza-home-2024&zip_code=10115&consumption=3500" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "offer_item_price_results": [
    {
      "name": "Energy Price",
      "price_net": 28.50,
      "price_gross": 33.92,
      "unit": "ct/kWh",
      "item_amount": 3500
    },
    {
      "name": "Grid Fee",
      "price_net": 8.20,
      "price_gross": 9.76,
      "unit": "ct/kWh",
      "item_amount": 3500
    },
    {
      "name": "Base Fee",
      "price_net": 96.00,
      "price_gross": 114.24,
      "unit": "€/year",
      "item_amount": 1
    }
  ],
  "total_price_results": {
    "ct/y": 159320.0,
    "ct/m": 13276.67
  }
}

Get Started

Core Concepts

Guides

Data & Analytics

Energy Prices, CO2 Savings, and Offer Calculator API

Overview

EPEX Spot Day-Ahead Prices

GET /v3/prices/epex_day_ahead/

Query Parameters

Response

Example: 24-Hour Window

CO2 Savings Calculation

GET /v3/prices/get_co2_savings/

Query Parameters

Response

Example Request

Example Response

Local Incumbent Utility Price

GET /v3/prices/get_local_utility_price/

Query Parameters

Response

Error: Ambiguous Address

Example Request

Example Response

Offer Calculator

GET /v3/offer_calculator/

Common Required Parameter

Additional Parameters by Tariff Type

Response: TariffOutput

Ambiguous Address: 300 Response

Example Request (Fixed Price Consumer)

Example Response

​Overview

​EPEX Spot Day-Ahead Prices

​GET /v3/prices/epex_day_ahead/

​Query Parameters

​Response

​Example: 24-Hour Window

​CO2 Savings Calculation

​GET /v3/prices/get_co2_savings/

​Query Parameters

​Response

​Example Request

​Example Response

​Local Incumbent Utility Price

​GET /v3/prices/get_local_utility_price/

​Query Parameters

​Response

​Error: Ambiguous Address

​Example Request

​Example Response

​Offer Calculator

​GET /v3/offer_calculator/

​Common Required Parameter

​Additional Parameters by Tariff Type

​Response: TariffOutput

​Ambiguous Address: 300 Response

​Example Request (Fixed Price Consumer)

​Example Response

Overview

EPEX Spot Day-Ahead Prices

GET /v3/prices/epex_day_ahead/

Query Parameters

Response

Example: 24-Hour Window

CO2 Savings Calculation

GET /v3/prices/get_co2_savings/

Query Parameters

Response

Example Request

Example Response

Local Incumbent Utility Price

GET /v3/prices/get_local_utility_price/

Query Parameters

Response

Error: Ambiguous Address

Example Request

Example Response

Offer Calculator

GET /v3/offer_calculator/

Common Required Parameter

Additional Parameters by Tariff Type

Response: TariffOutput

Ambiguous Address: 300 Response

Example Request (Fixed Price Consumer)

Example Response