SSB API (PxWebApi v2): praktisk guide

Endepunktene

Alle svarer på norsk med lang=no og på engelsk med lang=en.

GET /tables?lang=no&query=…: Søk i katalogen med fritekst. pastDays=N gir tabeller oppdatert siste N dager.
GET /tables/{id}/metadata?lang=no: Variablene, verdikodene og hvilke variabler som kan utelates. Ingen tall.
GET /tables/{id}/data?valueCodes[Var]=…: Tallene for utvalget ditt, som json-stat2, csv eller parquet (outputFormat).
POST /tables/{id}/data: Samme utvalg i JSON-kroppen. Nyttig når URL-en blir lang.
GET /config: Versjon og grenser, blant annet maxDataCells.

Utvalg med valueCodes

Du velger verdier per variabel. Variabler du utelater, blir summert av SSB hvis tabellen tillater det.

valueCodes[Region]=0301,4601: en liste med koder, her Oslo og Bergen.
valueCodes[Tid]=top(2): de to nyeste periodene.
valueCodes[Kjonn]=*: alle verdier, for eksempel begge kjønn hver for seg.

Metadata sier hvilke variabler som kan utelates (elimination). Variabler som ikke kan utelates, må du velge. Tabell 13760 har for eksempel trend, sesongjustert og ikke sesongjustert side om side, og da må du bestemme deg for én.

Eksempler

Folketallet i Oslo og Bergen de to siste årene, fra tabell 07459.

Python

import requests

url = "https://data.ssb.no/api/pxwebapi/v2/tables/07459/data"
params = {
    "lang": "no",
    "outputFormat": "csv",
    "valueCodes[Region]": "0301,4601",   # Oslo og Bergen
    "valueCodes[Tid]": "top(2)",         # de to nyeste årene
    "valueCodes[ContentsCode]": "Personer1",
}
svar = requests.get(url, params=params, timeout=30)
svar.raise_for_status()
print(svar.text)

library(httr2)

svar <- request("https://data.ssb.no/api/pxwebapi/v2/tables/07459/data") |>
  req_url_query(
    lang = "no", outputFormat = "csv",
    `valueCodes[Region]` = "0301,4601",
    `valueCodes[Tid]` = "top(2)",
    `valueCodes[ContentsCode]` = "Personer1"
  ) |>
  req_perform()

folketall <- read.csv(text = resp_body_string(svar))

JavaScript

const params = new URLSearchParams({
  lang: 'no',
  outputFormat: 'json-stat2',
  'valueCodes[Region]': '0301,4601',
  'valueCodes[Tid]': 'top(2)',
  'valueCodes[ContentsCode]': 'Personer1',
});
const svar = await fetch(`https://data.ssb.no/api/pxwebapi/v2/tables/07459/data?${params}`);
if (!svar.ok) throw new Error(`SSB svarte ${svar.status}`);
const data = await svar.json(); // json-stat2: data.value og data.dimension

POST med JSON-kropp

curl -X POST "https://data.ssb.no/api/pxwebapi/v2/tables/07459/data?lang=no&outputFormat=json-stat2" \
  -H "content-type: application/json" \
  -d '{"selection": [
        {"variableCode": "Region", "valueCodes": ["0301"]},
        {"variableCode": "Tid", "valueCodes": ["top(1)"]},
        {"variableCode": "ContentsCode", "valueCodes": ["Personer1"]}
      ]}'

Grensene

30 kall i minuttet per IP-adresse. /config oppgir 0, men den dokumenterte grensen gjelder. Hold omtrent to sekunder mellom kall, og vent et helt minutt etter et 429-svar.
800 000 celler per datakall. Antall celler er produktet av antall valgte verdier i hver variabel.
Publisering og vedlikehold. SSB publiserer klokken 08.00 og oppdaterer metadata rundt 05.00 og 11.30. I disse vinduene kan tabeller som finnes, svare 404 i noen minutter.
Statusflagg i data. .. ikke tilgjengelig, . ikke aktuelt, : konfidensielt, - null.

Fellen med kommunenumre

Kommunene fikk nye numre ved reformene i 2020 og 2024. Mange tabeller fører eldre år under de gamle numrene, så en tidsserie for én kode kan stoppe eller begynne midt i perioden. Sjekk hvilke år koden har tall for i metadata, eller velg en tabell med dagens inndeling. Les mer i fem feller når AI henter SSB-tall.

Finn tabell-ID-en først

SSBs eget søk (/tables?query=) leter etter ordene du skriver. Spør du med andre ord enn SSB bruker, finner det ofte ikke tabellen.

Finn tabell søker på betydning og lar en språkmodell velge. I egen kode kan du bruke det samme søket via Companybook-gatewayen (Plus-planen). Den svarer med tabell-ID, tittel, periode og variabler, og kan også hente metadata og data med de samme reglene som over.

Companybook-gatewayen

curl -X POST https://api.companybook.co/v1/gateway/ssb \
  -H "Authorization: Bearer $COMPANYBOOK_API_KEY" \
  -H "content-type: application/json" \
  -d '{"action": "search", "query": "arbeidsledighet per måned", "limit": 3}'

Gatewayen henter tallene fra SSB og deler SSBs grense på 30 kall i minuttet mellom alle brukerne. Er grensen nådd, svarer den 429 med en Retry-After-header som sier hvor mange sekunder du skal vente. Kontrakten står i OpenAPI-beskrivelsen.

Når passer MCP bedre?

Skal en AI-agent svare på spørsmål med SSB-tall, slipper du å skrive koden over. Med SSB MCP fra Companybook finner agenten tabellen, leser metadata, velger koder og henter tallene selv. Skriv kode når du trenger de samme tallene igjen og igjen, for eksempel i et dashbord eller en nattlig jobb.

Data og metadata: Statistisk sentralbyrå, lisensiert under CC BY 4.0. Companybook er ikke tilknyttet SSB.

Command Palette