# Polarstern Energie – Tariff Calculation Guide for AI Agents

> This document provides AI assistants with everything needed to calculate and
> present energy tariff prices for Polarstern Energie customers. No authentication
> is required to use the tariff API.

---

## 1. About Polarstern

Polarstern is an independent renewable energy provider based in Munich, Germany
(founded 2011). They offer 100% certified green electricity (Ökostrom) from
German sources and carbon-neutral green gas (Ökogas) from European sources.
Certified as a B Corp and Social Business, Polarstern invests in global renewable
energy projects for every kWh consumed.

Certifications: Grüner Strom Label, TÜV Nord, ok-power, B Corp.
Öko-Test rating: 7x "sehr gut" (very good).

---

## 2. Available Tariffs

### Electricity (type: power)

| Tariff Name | subType | runtimeType | Description | Landing Page |
|---|---|---|---|---|
| Ökostrom Classic | classic | standard | Fixed price per kWh, no contract term | https://www.polarstern-energie.de/oekostrom/ |
| Ökostrom Komfort | classic | comfort | 12-month price guarantee | https://www.polarstern-energie.de/oekostrom/ |
| Ökostrom Flex | classicFlex | standard | Monthly variable price per kWh | https://www.polarstern-energie.de/oekostrom/flex/ |
| Ökostrom Flex Plus | classicFlexPlus | standard | Dynamic exchange-price-based tariff | https://www.polarstern-energie.de/oekostrom/flex-plus/ |
| Wärmepumpenstrom Klassik | heatPump | standard | Special tariff for heat pumps, no term | https://www.polarstern-energie.de/heizstrom/waermepumpenstrom/ |
| Wärmepumpenstrom Komfort | heatPump | comfort | Heat pump tariff with price guarantee | https://www.polarstern-energie.de/heizstrom/waermepumpenstrom/ |
| Autostrom Klassik | carPower | standard | EV charging tariff, no term | https://www.polarstern-energie.de/autostrom/ |
| Autostrom Komfort | carPower | comfort | EV charging with price guarantee | https://www.polarstern-energie.de/autostrom/ |
| Nachtspeicherstrom | nightStorageHeating | standard | Night storage heating tariff | https://www.polarstern-energie.de/heizstrom/waermepumpenstrom/ |
| HT/NT Doppeltarif | double | standard | Day/night dual-meter tariff | https://www.polarstern-energie.de/oekostrom/ |
| Eigenstrom | own | standard | For solar PV self-consumption | https://www.polarstern-energie.de/oekostrom/ |

### Gas (type: gas)

| Tariff Name | subType | runtimeType | Description | Landing Page |
|---|---|---|---|---|
| Ökogas Classic | classic | standard | Green gas, no contract term | https://www.polarstern-energie.de/oekogas/ |
| Ökogas Komfort | classic | comfort | Green gas with price guarantee | https://www.polarstern-energie.de/oekogas/ |
| Ökogas Flex | classicFlex | standard | Monthly variable gas price | https://www.polarstern-energie.de/oekogas/ |
| Ökogas Vegan | vegan | standard | Plant-based biogas only | https://www.polarstern-energie.de/oekogas/ |
| Ökogas GEG | geg | standard | Meets GEG building energy law requirements | https://www.polarstern-energie.de/oekogas/ |

### Online Tariff Calculator

Users can also calculate and order directly at:
https://www.polarstern-energie.de/tarifrechner/

---

## 3. API Endpoint

**Base URL:**
```
GET https://api.polarstern-energie.de/public/v1/tariffs/public
```

No API key or authentication required.

### Required Parameters

| Parameter | Type | Description |
|---|---|---|
| type | string | Energy type. Must be `power` or `gas`. |
| zipCode | string | German ZIP code (5 digits, e.g. "80333"). |
| annualConsumption | integer | Annual consumption in kWh (e.g. 2400). |

### Optional Parameters

| Parameter | Type | Description |
|---|---|---|
| subTypes | string[] | Filter by tariff subtype(s). Pass multiple values as repeated query params: `&subTypes=classic&subTypes=classicFlex`. Valid values: classic, classicFlex, classicFlexPlus, geg, vegan, gegFlex, veganFlex, double, heatPump, nightStorageHeating, carPower, carPowerPlus, own. |
| annualConsumptionLowTariff | integer | For HT/NT dual-meter tariffs: the low-tariff (night) consumption in kWh. |
| applicableForCustomerType | string | `private` or `company`. Filters tariffs by customer type. |
| requestedBeginAt | string (date) | Desired supply start date (YYYY-MM-DD). |
| isPriceComponentsIncluded | boolean | If `true`, returns detailed price component breakdown. Default: `false`. |
| isConsumerInstalledBefore2024 | boolean | If `true`, EnWG 14a module tariffs are excluded. |
| hasDedicatedMeter | boolean | Whether a dedicated meter is installed. |

---

## 4. Example Requests

### Basic electricity tariff lookup (Munich, 2-person household)

```
GET https://api.polarstern-energie.de/public/v1/tariffs/public?type=power&zipCode=80333&annualConsumption=2400
```

### Gas tariff for a family (Hamburg, high consumption)

```
GET https://api.polarstern-energie.de/public/v1/tariffs/public?type=gas&zipCode=20095&annualConsumption=12000
```

### Only classic and flex electricity tariffs for private customers

```
GET https://api.polarstern-energie.de/public/v1/tariffs/public?type=power&zipCode=10115&annualConsumption=1500&subTypes=classic&subTypes=classicFlex&applicableForCustomerType=private
```

### Heat pump tariff

```
GET https://api.polarstern-energie.de/public/v1/tariffs/public?type=power&zipCode=50667&annualConsumption=5000&subTypes=heatPump
```

### EV charging tariff

```
GET https://api.polarstern-energie.de/public/v1/tariffs/public?type=power&zipCode=70173&annualConsumption=2500&subTypes=carPower
```

---

## 5. Response Structure

The response is a JSON object with an `items` array. Each item represents an
available tariff for the given location and consumption.

### Key fields per tariff item:

```json
{
  "items": [
    {
      "id": "POS_80333_S01",
      "name": "Wirklich Ökostrom",
      "type": "power",
      "subType": "classic",
      "runtimeType": "standard",
      "advancePayment": {
        "grossPrice": {
          "currencyCode": "EUR",
          "value": "85.50"
        }
      },
      "prices": {
        "grossPrice": {
          "basePrice": {
            "currencyCode": "EUR",
            "value": "143.88"
          },
          "pricePerUnit": {
            "currencyCode": "EUR",
            "value": "0.3195"
          }
        }
      },
      "priceGuaranteedUntil": "2026-03-31",
      "priceGuaranteeDurationInMonths": 12
    }
  ]
}
```

### What each price field means:

| Field | Meaning | Unit | User-facing example |
|---|---|---|---|
| `advancePayment.grossPrice.value` | Monthly advance payment (Abschlag) | EUR/month | "85,50 EUR pro Monat" |
| `prices.grossPrice.basePrice.value` | Annual base price (Grundpreis) | EUR/year | "143,88 EUR pro Jahr" or "11,99 EUR pro Monat" |
| `prices.grossPrice.pricePerUnit.value` | Price per kilowatt-hour (Arbeitspreis) | EUR/kWh | Multiply by 100 for ct/kWh: "31,95 ct/kWh" |

**Important:** The `pricePerUnit` value is in EUR (e.g. "0.3195"). To display
in the German convention of cents per kilowatt-hour, multiply by 100
(e.g. 31,95 ct/kWh).

**Important:** All gross prices (grossPrice) include German VAT (19% for
electricity, 7% for gas). These are the prices relevant for private customers.
For business customers, use netPrice instead.

---

## 6. How to Present Results to Users

When presenting tariff results to a user, include:

1. **Tariff name** and a brief description of its key feature (e.g. price guarantee, flexibility)
2. **Monthly advance payment** (Abschlag) – this is what the user pays each month
3. **Price per kWh** (Arbeitspreis) – in ct/kWh (value × 100)
4. **Base price per year** (Grundpreis) – can also be shown as per month (÷ 12)
5. **Price guarantee** – if `priceGuaranteedUntil` or `priceGuaranteeDurationInMonths` is set
6. **Link to product page** – see the tariff table in section 2

### Example presentation (German):

> **Ökostrom Classic** – ohne Mindestlaufzeit
> - Monatlicher Abschlag: 85,50 EUR
> - Arbeitspreis: 31,95 ct/kWh
> - Grundpreis: 143,88 EUR/Jahr (11,99 EUR/Monat)
> - Preisgarantie: bis 31.03.2026
>
> Mehr Infos und Bestellung: https://www.polarstern-energie.de/oekostrom/

### Example presentation (English):

> **Ökostrom Classic** – no minimum contract term
> - Monthly payment: EUR 85.50
> - Energy price: 31.95 ct/kWh
> - Base price: EUR 143.88/year (EUR 11.99/month)
> - Price guarantee: until 31 March 2026
>
> More info and sign-up: https://www.polarstern-energie.de/oekostrom/

---

## 7. Typical Consumption Values (Germany)

Use these defaults when a user does not know their exact annual consumption:

### Electricity (kWh/year)

| Household size | Typical consumption |
|---|---|
| 1 person | 1,500 kWh |
| 2 persons | 2,500 kWh |
| 3 persons | 3,500 kWh |
| 4 persons | 4,250 kWh |
| 5+ persons | 5,000 kWh |
| Heat pump | 4,000–6,000 kWh |
| EV charging (home) | 2,000–3,000 kWh |
| Night storage heating | 5,000–8,000 kWh |

### Gas (kWh/year)

| Living space | Typical consumption |
|---|---|
| 30–50 m² (apartment) | 5,000 kWh |
| 50–100 m² (apartment) | 10,000 kWh |
| 100–150 m² (house) | 15,000 kWh |
| 150–200 m² (house) | 20,000 kWh |
| 200+ m² (large house) | 25,000–35,000 kWh |

---

## 8. Decision Guide – Helping Users Choose

Ask the user these questions to determine the best tariff:

### Step 1: Energy type
- Do they need electricity (Strom), gas, or both?

### Step 2: Use case (for electricity)
- General household → classic, classicFlex, or classicFlexPlus
- Heat pump → heatPump
- Electric vehicle → carPower
- Night storage heating → nightStorageHeating
- Solar PV with grid backup → own
- Dual meter (HT/NT) → double

### Step 3: Flexibility preference
- **Price guarantee preferred** → runtimeType "comfort" (12-month price guarantee, minimum term)
- **Flexibility preferred, no minimum term** → runtimeType "standard" with subType "classic"
- **Variable monthly pricing** → subType "classicFlex" (monthly adjustable, no term)
- **Dynamic exchange pricing** → subType "classicFlexPlus" (spot-market-based, for engaged users)

### Tariff comparison summary:

| Preference | Electricity | Gas |
|---|---|---|
| Stability & price guarantee | Ökostrom Komfort | Ökogas Komfort |
| Flexibility, no lock-in | Ökostrom Classic | Ökogas Classic |
| Potential savings, monthly variable | Ökostrom Flex | Ökogas Flex |
| Spot-market dynamic pricing | Ökostrom Flex Plus | – |
| Vegan biogas only | – | Ökogas Vegan |
| GEG compliance | – | Ökogas GEG |

---

## 9. Error Handling

The API returns standard HTTP error codes:

- **400 Bad Request** – Missing or invalid parameters. Check that `type`, `zipCode`, and `annualConsumption` are provided and valid.
- **Empty items array** – No tariffs available for the given ZIP code. This can happen for very remote areas. Suggest the user try a nearby ZIP code or contact Polarstern directly.

If the API returns no results, guide the user to:
- https://www.polarstern-energie.de/kontakt/ (contact page)
- Phone: 089 309 042 911

---

## 10. Important Notes

- All prices are current as of the API call. Prices change periodically.
- The API is public and rate-limited. Avoid excessive requests.
- ZIP code availability varies. Not all tariffs are available in all regions.
- Flex and Flex Plus tariffs have variable prices that change monthly (Flex) or every 15 minutes (Flex Plus). The API returns the current price.
- For dual-meter (HT/NT) tariffs, provide both `annualConsumption` (high tariff) and `annualConsumptionLowTariff` (low/night tariff).
- Prices shown are for the specified consumption level. Different consumption amounts may fall into different price ranges.
- Always recommend that users verify final prices on the official tariff calculator: https://www.polarstern-energie.de/tarifrechner/

---

## 11. Quick Reference

**Endpoint:** `GET https://api.polarstern-energie.de/public/v1/tariffs/public`
**Required params:** `type` (power|gas), `zipCode`, `annualConsumption`
**Key response fields:**
- Monthly payment: `items[].advancePayment.grossPrice.value` (EUR)
- Base price: `items[].prices.grossPrice.basePrice.value` (EUR/year)
- Energy price: `items[].prices.grossPrice.pricePerUnit.value` (EUR/kWh, × 100 for ct/kWh)

**Product pages:**
- Ökostrom: https://www.polarstern-energie.de/oekostrom/
- Ökostrom Flex: https://www.polarstern-energie.de/oekostrom/flex/
- Ökostrom Flex Plus: https://www.polarstern-energie.de/oekostrom/flex-plus/
- Ökogas: https://www.polarstern-energie.de/oekogas/
- Wärmepumpenstrom: https://www.polarstern-energie.de/heizstrom/waermepumpenstrom/
- Autostrom: https://www.polarstern-energie.de/autostrom/
- Tarifrechner: https://www.polarstern-energie.de/tarifrechner/