Skip to content
SVERIGEFAKTA.com

API 1.0

Sverigefakta Open Data API

A read-only HTTP API over the same verified layer that powers the site: observations, metrics, municipalities, rankings, comparisons and the revision log. No endpoint computes anything of its own.

SF-ID

Every observation has a permanent identifier in the form SF.<METRIC>.<GEO>.<PERIOD>. The same ID is used by the site, the API, the embeds and the MCP tools, in both languages.

SF.FOLKMANGD.0180.2024
SF.FOLKMANGD.1280.2024

Endpoints

  • GET /api/v1/observations/{sf-id}

    One verified observation with raw value, unit, source and provenance.

    https://sverigefakta.com/api/v1/observations/SF.FOLKMANGD.0180.2024

  • GET /api/v1/observations

    Bounded collection for one municipality. Filters: geo (required), metric, amne, period, from, to, limit.

    https://sverigefakta.com/api/v1/observations?geo=0180&metric=folkmangd&from=2015&to=2024

  • GET /api/v1/metrics

    Metric catalogue with titles, units, source, KPI ID, registered aliases and capabilities. Publicly approved metrics only (fail closed).

    https://sverigefakta.com/api/v1/metrics?query=folkmangd

  • GET /api/v1/metrics/{metric}

    Provenance for one public metric: publisher, official title, KPI ID, dataset reference, source URL, geography and period semantics. Unknown or non-public metrics return 404.

    https://sverigefakta.com/api/v1/metrics/koladats-arbetsloshet-18-65

  • GET /api/v1/municipalities

    Municipality register: code, name, slug and county. Exact matches are flagged separately.

    https://sverigefakta.com/api/v1/municipalities?query=Malmö

  • GET /api/v1/rankings

    Ranking engine: shared period, competition ranking and a 90% coverage gate.

    https://sverigefakta.com/api/v1/rankings?metric=folkmangd&limit=10

  • GET /api/v1/compare

    Compare 2–4 municipalities. Common period and identical unit only — never mixed years.

    https://sverigefakta.com/api/v1/compare?municipalities=stockholm,malmo&metrics=folkmangd

  • GET /api/v1/revisions

    The revision log filtered by id, kommun, metric, type, after, before and limit.

    https://sverigefakta.com/api/v1/revisions?id=SF.FOLKMANGD.0180.2024

Read-only, public data and limits

  • Only GET and OPTIONS are served. No endpoint can create, ingest, apply or publish anything.
  • Only publicly approved metrics from the canonical registry are exposed. If public status cannot be established, the metric is omitted (fail closed).
  • Provenance comes from the existing registry and source references — never fabricated. Unknown fields are null.
  • Collections are bounded: observations default to 200 and max 1000 per request, metrics default to 20 and max 50. Ordering is deterministic (metric, then period).
  • Out-of-range or malformed parameters return 400; unknown or non-public resources return 404.

Response shape

{
  "ok": true,
  "apiVersion": "1.0",
  "license": "CC BY 4.0",
  "docs": "https://sverigefakta.com/api",
  "data": { }
}
{
  "ok": false,
  "apiVersion": "1.0",
  "error": { "code": "not_found", "message": "...", "details": {} }
}

Error codes

invalid_request
Invalid or unknown parameter.
invalid_metric
The metric is not in the registry.
invalid_geo
Unknown municipality code or slug.
invalid_period
The period is not a valid year.
invalid_range
from is greater than to.
ambiguous
Several candidates match — be more specific.
not_found
No verified resource with that ID.
insufficient_coverage
Below 90% coverage — no ranking is returned.
no_common_period
The municipalities share no common year.
incomparable
The metrics cannot be compared.
unsupported
The query is not supported by the engine.
unavailable
The value is missing in the verified layer.

Precision and coverage

  • Values are returned exactly as the source reports them. The API never rounds.
  • NaN and Infinity never appear in a successful response.
  • Rankings require at least 90% municipal coverage for the shared period; below that the API returns insufficient_coverage instead of a misleading list.
  • Comparisons use one common period and one unit for all municipalities.
  • Locale affects labels and citation text only — never the ID, value, metric, geo, period, source or content hash.

HTTP

  • GET and OPTIONS only. No authentication, no writes.
  • CORS: Access-Control-Allow-Origin: * without credentials.
  • Cache: public, max-age=3600, stale-while-revalidate=86400
  • ETag is deterministic; identical data yields an identical tag and a 304 on If-None-Match.

Embeds

Every data point can be embedded read-only, with source, period, SF-ID and a link back to Sverigefakta. Embeds are noindex.

<iframe src="https://sverigefakta.com/embed/observation/SF.FOLKMANGD.0180.2024" title="Sverigefakta" width="100%" height="220" loading="lazy"></iframe>
<iframe src="https://sverigefakta.com/embed/chart?geo=0180&metric=folkmangd" title="Sverigefakta" width="100%" height="360" loading="lazy"></iframe>

Licence and attribution

Sverigefakta's compilation, API responses and embeds are published under CC BY 4.0. Attribute Sverigefakta and link to the data point. The underlying data belongs to the original authority — cite it as reported in the source field, under that authority's own terms.

MCP

The same verified layer is available to AI assistants through Sverigefakta's MCP server, which exposes the identical read-only tools.