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

# Find one tariff

> Start from an operator, narrow to a single tariff, read it in full.

`GET /api/tariff/find` is a guided funnel. You give it as much as you know, and
it returns two things: the choices still open to you, and — once the funnel
leaves exactly one — the tariff itself.

It never offers a choice that leads nowhere. If an operator has no NE5 tariffs,
NE5 is not in `choices.voltages`.

## The funnel

**1. Give it an operator and a year**

```bash theme={null}
curl "$TARIFF_API/api/tariff/find?dso=10117012345&period=2026"
```

```json theme={null}
{
  "dso": { "vse_number": "10117012345", "operator_id": "5", "name": "AEW Energie AG" },
  "period": 2026,
  "selection": { "voltage": null, "type": null, "name": null },
  "choices": {
    "voltages": [7],
    "types": ["electricity", "grid", "metering", "regional_fees"],
    "tariffs": [
      { "name": "AEW Classic Standard-Tarif E", "type": "electricity",
        "voltage_level": 7, "is_feedin": false, "is_dynamic": false,
        "is_eco": false, "verified": true }
    ]
  },
  "tariff": null
}
```

**2. Narrow by grid level and type**

```bash theme={null}
curl "...&voltage=7&type=electricity"
```

`choices.tariffs` now lists only NE7 electricity tariffs. Each entry already
carries `is_eco`, `is_dynamic` and `verified`, so a picker can be built
without a second request.

**3. Name one — or don't, if only one remains**

```bash theme={null}
curl "...&voltage=7&type=electricity&name=AEW%20Classic%20Standard-Tarif%20E"
```

When the funnel leaves exactly one tariff, `tariff` is filled in even
without a `name`. An operator with a single NE3 tariff needs no third click.

## What you get back

```json theme={null}
{
  "tariff": {
    "name": "AEW Classic Standard-Tarif E",
    "type": "electricity",
    "form": "constant",
    "customer_type": "Privat- und Gewerbekunden bis 50'000 kWh/a.",
    "voltage_level": 7,
    "is_feedin": false,
    "is_dynamic": false,
    "is_eco": false,
    "energy_rp": 11.4,
    "energy_min_rp": 11.4,
    "energy_max_rp": 11.4,
    "base_chf_month": 0.0,
    "power_chf_kw_month": null,
    "windows": [{ "label": "Einheitstarif", "rp": 11.4 }],
    "valid_from": "2026-01-01",
    "valid_to": "2026-12-31",
    "provenance": {
      "state": "verified",
      "verified": true,
      "label": "reviewer-validated",
      "note": "a reviewer confirmed these values against the PDF",
      "stage": "tarif_validiert"
    },
    "corrected": false,
    "comment": ""
  },
  "comparison": {
    "tariff_rp": 11.4,
    "median_rp": 12.11,
    "pct": -5.9,
    "basis": "energy price only",
    "reference": "Swiss median energy price, H4 household, 2026"
  },
  "source": {
    "sheet": "/api/v1/dsos/10117012345/tariffsheet?period=2026",
    "registered_url": "https://www.aew.ch/json-2026"
  }
}
```

Prices are in **Rp/kWh** here, converted from the operators' CHF/kWh.

## The comparison, and when it is absent

`comparison` puts the tariff's energy price against the national median energy
price for an H4 household (4,500 kWh/year).

> [!WARNING]
>
> `comparison` is `null` whenever a fair comparison does not exist, and this is
> deliberate rather than a gap:
>
> * a **grid-usage** tariff has no energy price;
> * a **feed-in** tariff is a remuneration, not a price;
> * a **dynamic** tariff has no fixed rate to compare.
>
> No substitute number is invented for these. If you see `null`, there is nothing
> honest to put there.

`basis` says exactly what was compared. It reads `"energy price only"` — never a
total bill, because a total depends on the consumption profile and the grid
level, which a named tariff does not carry.

## Every state is a link

The query string that drives the endpoint is the same one the public map uses,
so any point in the funnel is shareable and bookmarkable:

```
/?dso=10117012345&period=2026&voltage=7&type=electricity&name=AEW%20Classic%20Standard-Tarif%20E
```

## Errors

| Status | When |
| - | - |
| `404` | Unknown operator, or no tariffs at all for that operator and year. |
| `200` with `tariff: null` | The funnel has not narrowed to one yet — keep going, `choices` tells you what is left. |

> [!TIP]
>
> Looking for the operator's original document rather than the harmonized reading?
> `source.registered_url` is the file the operator itself published, and
> `source.sheet` reconstructs the whole tariff sheet in the official VSE
> submission format.


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