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

# Coverage and empty answers

> Telling 'nobody offers that' apart from 'we don't have the data'.

The most dangerous thing an API like this can do is return a short list without
saying what the list is short *of*. A reader who asks for dynamic tariffs and
gets six results will conclude one of two very different things, and the
response has to decide which.

So filtered endpoints return the denominator.

## The rule

`/api/map/tariffs` reports three counts on every request:

| Field | Means |
| - | - |
| `n_total` | Operators with **any** consumption tariff for that year and grid level. The honest denominator. |
| `n_matched` | Operators with at least one tariff matching your filter. |
| `n_priced` | Of those, how many have a fixed rate that can be shown as a number. |

A response where `n_matched` is far below `n_total` is a real answer about the
Swiss market, not a gap in collection.

## What that looks like in practice

Tariff year 2026, grid level NE7, consumption side:

| Filter | `n_matched` / `n_total` | `n_priced` | Median |
| - | - | - | - |
| electricity, any product | 480 / 502 | 477 | 12.70 Rp/kWh |
| grid usage | 498 / 502 | 497 | 9.31 Rp/kWh |
| electricity, eco only | 110 / 502 | 110 | 12.48 Rp/kWh |
| electricity, dynamic only | **6 / 502** | **1** | — |

Eco products are offered by about a fifth of operators. Dynamic household
tariffs, for all the attention they get, are offered by six.

## A match without a price is still a match

Look again at the dynamic row: six operators match, one has a rate.

That is not a data quality problem — it is what a dynamic tariff *is*. Its price
is a time series, not a number, so there is nothing to put in a `rate_rp` field.

Those five operators are returned with `rate_rp: null` and `priced: false`:

```json theme={null}
"operators": {
  "486": {
    "rate_rp": null,
    "priced": false,
    "n_tariffs": 1,
    "verified": true,
    "example": "EKZ Energie Dynamisch"
  }
}
```

> [!WARNING]
>
> Dropping unpriced matches would make the dynamic filter answer **"1 of 502"** for
> something six operators offer — the single most misleading number this API could
> produce. If you re-aggregate this data yourself, count `n_matched`, and average
> over `n_priced`.

To get actual prices for those operators, ask for the
[time series](https://docs.tariffs.nlead.ch/guides/time-series.md) instead.

## Coverage is not uniform across fields

Before building on a field, check how populated it is:

| Field | Populated for |
| - | - |
| `tariff_type`, `tariff_form`, `customer_type` | Effectively every tariff |
| `is_eco` | Every tariff; \~22% of operators offer at least one |
| `voltage_level` | Every tariff |
| `has_dynamic` | Every tariff; true for 21 operators across all types and levels |
| Feed-in matrix detail (`technology`, `capacity_kw_*`, `season`, `time_band`) | Only where the operator publishes a structured feed-in sheet |

`GET /api/v1/periods` gives the live per-stage, per-year breakdown; `GET
/api/readiness` gives collection progress against the programme's deadlines.

## Years

A tariff year is collected during the preceding year, so the current year is
always more complete than the coming one. Ask `/api/v1/periods` rather than
assuming — and when you want "the year that is being collected now",
`/api/meta` returns it as `default_period`.


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