> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenaza.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Energy Prices, CO2 Savings, and Offer Calculator API

> Retrieve EPEX spot prices, calculate CO2 savings, look up local utility tariffs, and generate customer-facing offer quotes via the tariff calculator.

## 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

```bash theme={null}
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>"
```

```json theme={null}
[
  {
    "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

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

### Example Response

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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:

```json theme={null}
{
  "zipcode": "60313",
  "streets": [
    ["Schillerstraße", "Frankfurt am Main"],
    ["Schillerstraße", "Frankfurt an der Oder"]
  ]
}
```

### Example Request (Fixed Price Consumer)

```bash theme={null}
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

```json theme={null}
{
  "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
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.