The stages
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:/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
Publishing figures to the public, or quoting them
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 before assuming the remainder is
representative.Analysis, comparison, research
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.
Feeding a system that acts on prices
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.
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.