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

# Provenance

> Where a figure came from, and whether a human has checked it.

Most Swiss grid operators publish their tariffs as a PDF. Reading a PDF reliably
is not a solved problem, so this service does two things at once: it reads them
anyway, and it never lets you mistake a machine's reading for a checked one.

Every tariff carries a **stage**. It is the single most important field in the
dataset.

## The stages

| `stage` | Meaning | Trust |
| - | - | - |
| `tarif_validiert` | A reviewer confirmed the values against the operator's own document. | Verified |
| `pipeline_korrigiert` | A deterministic unit correction was applied — a value published in the wrong unit, fixed by rule, original preserved. | Verified |
| `API_validiert` | Taken from the operator's own machine-readable publication. | Verified |
| `pipeline` | Fetched from the operator's registered file by the collector. | Verified |
| `ungeprüft` | Present in the operator's file but not yet through the checks. | Verified |
| `ki` | Read out of the operator's PDF by a model. **Not confirmed by anyone.** | Unverified |

Only `ki` is unverified. Everything else traces back to something the operator
itself published in machine-readable form, or to a person who looked.

## Why unverified figures are published at all

Because withholding them would be worse. When the choice was measured against
the real dataset, hiding unconfirmed readings would have blanked **161
operators covering 10,573 km² — 37% of the Swiss supply area, including all of
Ticino**. A map with a hole where Ticino should be teaches the reader that
Ticino has no tariffs, which is false.

So the rule throughout the service is: **show it, mark it, never drop it.** On
the map, unverified areas are drawn with a hatch. In the API, they say so.

## Reading provenance in a response

The reader-facing endpoints expand the stage into something you can put in front
of a person:

```json theme={null}
"provenance": {
  "state": "unverified",
  "verified": false,
  "label": "machine-read",
  "note": "read from the DSO's PDF by the model and not yet confirmed by a reviewer — treat as provisional",
  "stage": "ki"
}
```

`/api/map/tariffs` reports the same thing per operator as a boolean `verified`,
computed over the tariffs that actually matched your filter rather than over the
operator as a whole.

## Choosing a policy

> [accordion] Publishing figures to the public, or quoting them
>
> Filter to verified only. In `/api/v1`, that means excluding
> `stage == "ki"`. Expect to lose a large minority of operators — check
> [Coverage](https://docs.tariffs.nlead.ch/concepts/coverage.md) before assuming the remainder is
> representative.

> [accordion] Analysis, comparison, research
>
> Take everything, and carry the stage through to your output. The unverified
> readings are usually right; they are simply not guaranteed, and your reader
> deserves the same distinction you were given.

> [accordion] Feeding a system that acts on prices
>
> Take everything, act on verified figures only, and treat an unverified one
> as a prompt to fetch the operator's own document — the URL is in
> `source.registered_url` on `/api/tariff/find` and in `json_url` on
> `/api/v1/dsos`.

## One tariff, several stages

The same tariff often exists at more than one stage: a model read it in
September, a reviewer confirmed it in November. Both rows are kept — the
correction history is part of the record.

Endpoints that reduce to one answer per tariff pick the highest stage present,
per tariff, not per operator. `/api/v1/dsos/{dso_id}/tariffs` does this by
default (`best_stage_only=true`); pass `false` to see the full history.

> [!NOTE]
>
> Best stage is resolved **per tariff identity**, so an operator whose NE7 tariffs
> are validated and whose NE3 tariff is only machine-read keeps both. Resolving it
> per operator instead would silently drop the NE3 tariff.


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