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

# Accuracy

> How close our bills come to ElCom's published figures, measured every night.

Every operator's tariffs reach this database by a different road: the
operator's own machine-readable sheet, a reviewer, or a model reading a PDF.
Provenance tells you which road a figure took. Accuracy tells you whether the
result is right.

ElCom, the federal regulator, publishes for every operator and year what a
standard customer pays: a household using 4'500 kWh a year (category **H4**),
2'500 kWh (H2), and businesses from 8'000 kWh (C1) to 7.5 GWh at medium voltage
(C7). It splits that figure into energy, grid usage, community fees and the
national charges. Every night this service composes the same customer's bill
from the tariffs it holds and compares the two.

```bash theme={null}
curl "$TARIFF_API/api/v1/accuracy?period=2027"
```

```json theme={null}
{
  "period": 2027,
  "measured": "2026-11-19",
  "band_pct": 5,
  "headline": "H4",
  "categories": [
    {"category": "H4", "kwh": 4500, "kind": "household",
     "operators": 527, "billed": 505, "within_band": 360, "within_2pct": 236,
     "share_within_band": 0.713, "median_miss_pct": 2.2},
    {"category": "C3", "kwh": 150000, "kind": "business",
     "operators": 512, "billed": 492, "within_band": 252, "within_2pct": 158,
     "share_within_band": 0.512, "median_miss_pct": 4.5}
  ],
  "trend": [{"day": "2026-11-19", "within_band": 360, "operators": 505}]
}
```

The response lists all nine categories, H4 and H2 and C1 to C7; two are shown
here.

| Field | Meaning |
| - | - |
| `operators` | Operators ElCom publishes a figure for, in this category. |
| `billed` | Of those, the operators we could compose a bill for. |
| `within_band` | Bills within ±`band_pct` % of ElCom's total. |
| `within_2pct` | Bills within ±2 %. |
| `share_within_band` | `within_band` of `billed`: every operator counts the same, a village cooperative as much as the cantonal utility. |
| `area_share_within_band` | The same share with each operator weighted by the area it supplies, so the large operators weigh what they serve. |
| `median_miss_pct` | The typical distance from ElCom's total, in percent. |
| `trend` | The headline category, night by night. |

> [!NOTE]
>
> Business bills (C1–C7) are harder than household bills: their grid tariffs
> carry a price per kW of peak demand, and many operators file business products
> in separate documents. About half are within ±5 % today, with a median miss of
> 4 to 5 %, against 71 % and 2.2 % for households. Check a business bill's own
> `elcom_check` before relying on it ([business bills](https://docs.tariffs.nlead.ch/guides/business-bill.md)).

The same numbers, with the method in full, are on the
[accuracy page](https://ch-el-tarif-db.azurewebsites.net/accuracy).

## What a miss means

A bill can miss ElCom's figure for reasons that are not an error in the data.
ElCom's figure is for its standard customer, on the operator's standard
product; an operator with several household products or a dynamic tariff can
be billed correctly and still differ. A miss is a place to look, not a verdict.

## Operators whose fee differs by municipality

ElCom's figure for an operator is an average over the municipalities it
supplies, and within one operator only the community fee differs between them:
Romande Energie's 262 municipalities range from 27.3 to 29.8 Rp/kWh for H4.
Where the operator's sheet states the fee per municipality, the bill can be
exact for each, so the measurement prices every municipality ElCom has a figure
for and compares the one with the median miss against ElCom's figure for that
municipality. Not the best match, which would flatter the result: the typical
one. Where the sheet has one fee for the whole area, the operator's average
stays the reference.

To get an exact bill for one municipality, pass its BFS number as `bfs` to
`/api/bundle`.

When a bill misses, the measurement names the part that misses most: energy,
grid usage, metering, community fees, the national charges, last year's prices
still on file, or a part with no price at all. Those causes drive what the
collector does next; they are not part of the public response.

## What the measurement is not

> [accordion] It is not independent everywhere
>
> ElCom's household figure (H4) is also what some corrections are learned
> from: which product is an operator's standard one, which grid tariff a
> household is on, whether a grid price already contains the national
> charges. For those operators H4 is no longer an independent check. H2 never
> feeds any learning, so it is the cleaner test.

> [accordion] A stand-in is never counted as a match
>
> Where an operator has published no tariffs at all, the bill falls back to
> ElCom's own figures, marked as such. Those bills are excluded: a figure
> compared with itself proves nothing.

> [accordion] It covers what ElCom publishes
>
> ElCom publishes standard categories, not every product. A dynamic tariff, a
> heat-pump product or a business on a negotiated contract is not measured.

## How far one bill can be trusted

Every composed bill (`/api/bundle`) carries a `confidence` block: the
strongest evidence behind that bill, so you can use the strong ones directly
and treat the rest with care.

```json theme={null}
"confidence": {
  "grade": "elcom_confirmed",
  "source": "operator_sheet",
  "estimated_parts": [],
  "elcom_check": {"category": "H4", "day": "2026-11-03", "dev_pct": -1.2,
                  "cause": "ok", "applies": true, "why_not": null}
}
```

| `grade` | Meaning |
| - | - |
| `elcom_confirmed` | Last night's check of this operator's bill at about this consumption came within ±5 % of ElCom's published total |
| `reviewed` | A reviewer confirmed every line against the operator's own document |
| `operator_sheet` | Read from the operator's machine-readable sheet |
| `ai_read` | At least one line was read out of a PDF by a model and is not yet confirmed |
| `last_years_energy` | The energy price is ElCom's figure for last year, not this year's: the operator's new prices are not on file yet. Grid and fees are this year's; `warnings` says so in words, and the energy line carries `last_years_price: true` |
| `elcom_standin` | The operator files no sheet; the bill is ElCom's own figures |

`source` is where the lines came from, whatever ElCom says about them.
`estimated_parts` names parts the sheet left empty and ElCom's figure filled
(the meter, the community fee), and a dynamic price estimated from its
published quarter-hour prices (`energy (dynamic)`). Such a line carries
`dynamic_estimate`, with the period, the number of prices and the method: the
mean over the last year, once a week or more is on file. `elcom_check` is the latest nightly check in
the ElCom category nearest your consumption. It applies only to the bill as
the database opens it, within 25 % of that category's consumption. Once you
choose another product or tariff, `applies` is `false` and `why_not` says why.


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