PxWebApi 2.0 beta
Via PxWebApi 2.0 kan man hente ut data fra alle tabeller i SSBs statistikkbank med http GET. Spørringen kan dermed være definert i selve URL-en. API-et viser også flere metadata for hver tabell enn tidligere. API-et har flere nye spørreparametre. Nærmere beskrivelse av spørringer og endepunkt finnes på PxApiSpecs/specs.md at master · PxTools/PxApiSpecs.
PxWebApi v1 vil leve videre parallelt med det nye API-et i flere år framover. Vær obs på at PxWebApi 2.0 beta inntil videre ikke er tilgjengelig om morgenen i tidsrommet kl. 05.00-08.15, samt lørdag og søndag.
Det begrensete API-et med ferdige datasett fjernes i løpet av 2025, siden PxWebApi 2.0 tilbyr GET-spørringer.
SSB tilbyr også et eget API mot «Standard klassifikasjoner og kodelister (Klass)». Se Klass API guide.
Du kan hente hele tabeller eller deler av tabeller. Grensene per uttrekk er 800.000 dataceller, og antall spørringer er for tiden 30 per 60. sekund. Se https://data.ssb.no/api/pxwebapi/v2-beta/config.
API-ene benytter Creative Commons-lisensen CC BY 4.0.
Finne tabeller
Du kan finne tabeller
- Via statistikkbankens grensesnitt PxWeb: https://www.ssb.no/statbank kan du lete opp tabeller. Noter tabellnummer (f.eks. 05810) og bruke dette i URL på formen https://data.ssb.no/api/pxwebapi/v2-beta/tables/05810?lang=no
- eller via selve API-et: https://data.ssb.no/api/pxwebapi/v2-beta/tables lister opp alle tabeller. Parameter pagesize angir hvor mange tabeller som tas med per side. Parameter pagenumber angir sidenummer i trefflista.
Søk etter tabeller med parameter query
Parameteren query søker i utgangspunktet i tabelltitler, variabler og variabelverdier. Søket er case-insensitivt. Filteret title begrenser søket til tittelfeltet.
Eksempler:
- Søk etter teksten "kakemiks" i alle tabeller
https://data.ssb.no/api/pxwebapi/v2-beta/tables?query=kakemiks - Søk etter tabellnummer i tittel
https://data.ssb.no/api/pxwebapi/v2-beta/tables?query=title:03013 NY - Alle titler med ordene "trend" og/AND som begynner på "anlegg", (trunkeringstegn *)
https://data.ssb.no/api/pxwebapi/v2-beta/tables?query=title:trend AND anlegg* NY - Søk etter "varenummer" og "HS" mindre enn 5 ord fra hverandre, (nærhetsoperator ~)
https://data.ssb.no/api/pxwebapi/v2-beta/tables?query="varenummer hs" ~5 - Søk etter ikke avslutta tabeller om barn:
https://data.ssb.no/api/pxwebapi/v2-beta/tables?query=barn NOT "avslutta serie"
Merk at mellomrom kodes i url som %20. Tegnene:" ( ) [ og ] kan i url bli kodet som henholdsvis %22, %28, %29, %5B, og %5D.
Søk etter tabeller som nylig er oppdatert
Bruk parameter pastdays om du ønsker å finne tabeller som er oppdatert i løpet av f.eks. de 3 siste dagene: https://data.ssb.no/api/pxwebapi/v2-beta/tables?pastdays=3
Grunnleggende informasjon om tabellen
Basisinformasjon om tabellen kan hentes med URL på formen
https://data.ssb.no/api/pxwebapi/v2-beta/tables/fem-sifret tabellnummer?lang=no
Eksempel fra tabell 05810: https://data.ssb.no/api/pxwebapi/v2-beta/tables/05810?lang=no
Her ser man blant annet tabelltittel label, første og siste periode i tidsserien (firstPeriod og lastPeriod) og hvilke variabler som inngår (variableNames). Path viser tabellens plassering(er) i emnestrukturen.
De samme metadata på engelsk får man med https://data.ssb.no/api/pxwebapi/v2-beta/tables/05810?lang=en.
Metadata for tabellen
Utfyllende metadata for et gitt tabellnummer kan hentes med URL på formen https://data.ssb.no/api/pxwebapi/v2-beta/tables/fem-sifret tabellnummer/metadata?lang=no . Metadataene vises i format json-stat2, der objekter vises som { } og lister som [ ]. Utsnitt herfra kan brukes til å lage spørringen.
Metadataene består av en tabelltittel label (nivå 1) samt en liste over variabler for tabellen. For variabelobjektene dimension (nivå 2) er de viktigste egenskapene:
- Variabelident (id)
- Variabelnavn (label)
- Eliminering (elimination)
Hvert variabelobjekt inneholder to lister (nivå 3), en med verdikoder index og en med presentasjonstekster for verdiene label.
Eksempel fra tabell 05810: https://data.ssb.no/api/pxwebapi/v2-beta/tables/05810/metadata?lang=no
For statistikkvariabler er det alltid oppgitt unit (måleenhet) og decimals (antall desimaler).
Per statistikkvariabel kan det under extension finnes:
- Pristyper (priceType: Current, Fixed, NotApplicable)
- Sesong- og kalenderjustering (adjustment: SesOnly, WorkOnly, WorkAndSes, None)
- Basisperiode (basePeriod)
- Måletype (measuringType: Stock, Flow, Average, Other)
Hente data fra tabell
Data (tall) for et gitt tabellnummer kan hentes med URL på formen https://data.ssb.no/api/pxwebapi/v2-beta/tables/fem-sifret tabellnummer/data?lang=no .
For tabell 05810 vil https://data.ssb.no/api/pxwebapi/v2-beta/tables/05810/data?lang=no gi en tabell fordelt på kjønn og alder for nyeste periode. Dette tilsvarer den default-uttrekket som man får når man velger samme tabell i PxWeb. Vær obs på at i default-tabellen vil kun to dimensjoner vil vise flere enn en verdi. For å hente ut tall i flere dimensjoner, må man presisere dette i API-spørringen (se neste avsnitt).
Spørringer mot en tabell
Du kan bruke PxWeb for å bygge opp API-spørringer, eller du kan benytte applikasjoner som Postman, Hoppscotch e.l. for å konstruere dine egne spørringer. I denne veiledningen viser vi eksempler på spørringer via Postman.
Parametre til bruk i spørringer
Bruk parameter lang om du ønsker engelsk språk. Default språk er norsk.
For å angi variabel og verdier, bruk valueCodes[variabel-id]=verdi-index1, verdi-index2 etc.
Du kan presisere en av flere kodelister til variabelen, bruk codeList[variabel-id]=kodeliste-id
Om kodelista er en gruppering, kan du bruke outputValues[variabel-id]=aggregated|single for å spesifisere om du ønsker aggregerte eller enkeltverdier.
Bruk outputformat om du ønsker å få ut noe annet enn default format.
Trunkere med stjerne, maskere enkelttegn med spørsmålstegn
I dette eksemplet fra tabell 03013 henter vi tall for statistikkvariabel (ContentsCode) KpiIndMnd for alle konsumgrupper med tosifret kode (??) og for alle måneder i 2020 (2020*):
URL-en som blir laget ser da slik ut: https://data.ssb.no/api/pxwebapi/v2-beta/tables/03013/data?valueCodes[Konsumgrp]=??&valueCodes[ContentsCode]=KpiIndMnd&valueCodes[Tid]=2020*
Det er mulig å sette trunkeringstegn både foran og bak søketermen.
Hente de nyeste periodene, eller første verdiene
Ønsker vi tall for de n nyeste månedene, kan vi bruke top(n):
Med [top(n, start)] kan man hente n verdier fra og med start-posisjonen. Bottom fungerer på samme måte som top, men henter verdier fra slutten av lista.
Hente alle verdier fra en gitt startverdi
Ønsker vi tall for alle verdier fra startverdi x, kan vi bruke from(x):
Hente alle verdier i et gitt spenn
Vi kan bruke [range (x,y)] for å hente alle verdier i spennet fra x til y:
Utformater
API-et kan gi resultatet i 7 hovedformater:
- json-stat2 (default)
- csv (tekstformat)
- px (brukes i PxWeb og PxWin)
- xlsx (Excel)
- html
- json-px
- parquet
Formatene csv, html og xlsx kan spesifiseres videre:
- UseCodes (vis koder)
- UseTexts (vis tekst)
- UseCodesAndTexts (vis koder og tekst)
- IncludeTitle (ta med tabelltittel)
Og for csv-filer kan man i tillegg spesifisere:
- SeparatorTab (tabulator mellom kolonner)
- SparatorSpace (mellomrom mellom kolonner)
- SeparatorSemicolon (semikolon mellom kolonner)
Eksempel:
Ved utformatene csv, html og xlsx bruker man stub for å angi hvilke variabler man vil plassere i forspalten av tabellen og heading for de variablene man vil plassere i tabellhodet.
Om man plasserer alle variabler i stub, får men en såkalt pivotvennlig tabell:
https://data.ssb.no/api/pxwebapi/v2-beta/tables/03024/data?valuecodes[ContentsCode]=*&valuecodes[Varegrupper2]=*&stub=VareGrupper2,Tid,ContentsCode&valuecodes[Tid]=top(3)&outputformat=csv&outputformatparams=separatorsemicolon,usecodesandtexts
Desimalskilletegn er . (punktum) for alle språk og alle formater, unntatt Excel på norsk der desimalskilletegnet er komma.
Eliminasjon
En eliminerbar variabel kan tas helt vekk fra spørringen.
Er variabelen eliminerbar (true) vises:
- enten en elimineringsverdi, vanligvis summen
- eller så aggregeres samtlige verdier til en.
Er variabelen ikke eliminerbar (false), må man velge noe fra den. Tid og statistikkvariabel (ContentsCode) er ikke eliminerbar.
Verdimengder
En variabel kan ha flere verdimengder (valuesets) tilknyttet. Disse vil i så fall være listet opp under endepunkt metadata, angitt som codeLists/vs. Eksempelvis kan regionvariabelen ha både fylkesliste og kommuneliste:
https://data.ssb.no/api/pxwebapi/v2-beta/codeLists/vs_Fylker?lang=no
https://data.ssb.no/api/pxwebapi/v2-beta/codeLists/vs_Kommun?lang=no
Man kan spesifisere hvilken verdimengde man vil hente tall fra på ved å spesifisere codelist når man henter ut data: https://data.ssb.no/api/pxwebapi/v2-beta/tables/01222/data?valueCodes[Region]=*&valueCodes[ContentsCode]=Folketallet1&valueCodes[Tid]=from(2022K1)&codelist[Region]=vs_Fylker
Grupperinger (aggregering eller seleksjon)
En variabel kan ha grupperinger tilknyttet. Grupperinger vil i så fall vises under endepunkt metadata, angitt som codeLists/agg. Et eksempel fra https://data.ssb.no/api/pxwebapi/v2-beta/tables/07459/metadata er Kommuner 2024, sammenslåtte tidsserier:
Fra https://data.ssb.no/api/pxwebapi/v2-beta/codeLists/agg_KommSummer?lang=no kan du se hvordan grupperingen er bygget opp:
Under valueMap kan du se hvilke kommunekoder som summeres opp til gruppekodene K-3101, K-3203 osv. Grupperingen benyttes sammen med outputValues[Region]= aggregated for å velge ut aggregerte tall, her for å summere opp tall for sammenslåtte kommuner og kommuner som har byttet kode i løpet av årene. Eksempel for Moss, som i 2020 ble slått sammen av kommunene 0104 og 0136, og som i 2024 byttet kode fra 3002 til 3103:
https://data.ssb.no/api/pxwebapi/v2-beta/tables/07459/data?lang=no&valueCodes[Region]=K-3103&valueCodes[Tid]=*&valueCodes[ContentsCode]=Personer1&codelist[Region]=agg_KommSummer&outputValues[Region]=aggregated
Et annet eksempel fra samme tabell er Fylker 2024-:
Fra https://data.ssb.no/api/pxwebapi/v2-beta/codeLists/agg_Fylker2024?lang=no kan du se hvordan grupperingen er bygget opp:
Her er code og valueMap like. Grupperingen benyttes sammen med outputValues[Region]= single for å velge ut noen verdier fra den fulle lista, i dette tilfellet den nyeste fylkesinndelingen. Eksempel:
https://data.ssb.no/api/pxwebapi/v2-beta/tables/07459/data?lang=no&valueCodes[Region]=*&valueCodes[ContentsCode]=Personer1&valueCodes[Tid]=top(1)&codelist[Region]=agg_Fylker2024&outputValues[Region]=single
Fotnoter
Eventuelle fotnoter er oppgitt under note, og kan være tilknyttet tabell, variabel eller verdi. Flere fotnoter kan være tilknyttet samme element. De er da adskilt med hermetegn og komma. Se f.eks.
https://data.ssb.no/api/pxwebapi/v2-beta/tables/12880/metadata.
Post-spørringer
PxWebApi 2.0 støtter også POST-spørringer. Se eksempel på https://github.com/janbrus/ssb-api-python-examples/blob/master/PxWebApi2/laks_nor.ipynb
Responskoder
Mulige feilkoder dersom spørringen ikke gir svar:
400 – Feil syntaks i spørringen.
403 – Sperre ved spørring om for stort datasett. API-ets grense er 800 000 celler (inkl. tomme celler). Statistikkbanken har ellers en grense på 300 000 celler.
404 – Ressurs ikke funnet
429 – For mange spørringer. Grensen i PxWebApi er 30 spørringer pr 60. sekund. Flere store spørringer bør uansett kjøres i sekvens. Vent til du har fått respons på den forrige, før du fyrer av den neste. Førøvrig har API-et med ferdige datasett har ingen slik grense.
503 – Time-out etter 60 sekunder. Kan komme ved stor belastning og ved store uttrekk som XLSX, som ikke anbefales.
Kjente mangler
subject-code viser konstant "al" og "subject-area" viser "Arbeid og lønn". Dette vil bli rettet.
Endepunkt navigation er inntil videre tatt bort. I stedet viser endepunkt table tabellens plassering(er) i emnestrukturen under Path.
PxWeb viser foreløpig bare POST-spørringer for PxWebApi v1, men vi vil senere også vise GET-spørring for PxWebApi v2.
Annet
Hvordan bruke Statistikkbanken
Før en bruker API-et bør en være fortrolig med Statistikkbanken. Ikke undervurder lenkene på Statistikkbankens hjelpesider og instruksjonsvideoene. Det er dessuten nyttig å følge med på siden som gir strukturelle endringer og tabeller som avsluttes og erstattes av nye.
Tabeller i Statistikkbanken har et alias som adressen:
https://www.ssb.no/stabank/table/5-sifret-tabellnr
For eksempel: https://www.ssb.no/tabell/05000
Spesialtegn i tabellene
API-et kan vise spesialtegn i stedet for tall:
. | Ikke mulig å oppgi tall Tall finnes ikke på det dette tidspunktet, fordi kategorien ikke var i bruk da tallene ble samlet inn. |
.. | Tallgrunnlag mangler Tall er ikke kommet inn i våre databaser eller er for usikre til å publiseres. |
: | Vises ikke av konfidensialitetshensyn Tall publiseres ikke for å unngå å identifisere personer eller virksomheter. |
I json-stat2 vises spesialtegnene under status, mens data vises som null.
JSON
JSON-syntaks se: https://www.json.org.
Vi anbefaler å ha en JSON viewer i nettleseren. Mange nettlesere har dette innebygd. Du kan også hente inn tillegg som f.eks. https://jsonview.com.
JSON-stat
JSON-stat er et format spesielt utviklet for vise statistiske tabeller, altså datasett med mange dimensjoner. JSON-stat representerer verdiene i datakubene som et flatt array (row-major order). Det viser en trestruktur, med hovedelementene dataset, dimension og value med tilknyttet status. I tillegg er statistikkvariabel, geografiske variabler og tid tildelt egne roller ('role'), for enkel tilgang.
Selv om API-et har 6 output-formater, anbefaler vi nå å benytte JSON-stat versjon 2. I motsetning til v1 listes elementene i logisk, og ikke tilfeldig, rekkefølge. V1 vil dessuten ha problem med de største datasettene.
JSON-stat benyttes av mange statistiske byråer, og API-ene til Eurostat og Verdensbanken. Det finnes dessuten ferdige biblioteker for bl.a.: Javascript, Python, R og Java.
For mer informasjon om formatet og biblioteker, se https://json-stat.org/.
For Javascript er JSON-stat Toolkit nyttig, spesielt for javascript. For å forstå strukturen på JSON-stat anbefales å prøve ut JSON-stat explorer som ligger her. Toolkit inkluderer også JSON-stat Command Line Conversion Tools. Disse fleksible konverteringsverktøyene der jsonstat2csv gir bedre tilpasset CSV. Denne forutsetter at node.js er installert.
- jsonstat2csv - converts JSON-stat into CSV
- arrow2jsonstat - converts an Apache Arrow file to JSON-stat
- csv2jsonstat - converts CSV into JSON-stat
- jsonstat2array - converts JSON-stat into an array of arrays
- jsonstat2arrobj - converts JSON-stat into an array of objects
- jsonstat2arrow - converts JSON-stat to the Apache Arrow format
- jsonstat2objarr - converts JSON-stat into an object of column-oriented arrays
- jsonstat2object - converts JSON-stat into a Google DataTable object
- jsonstatdice - creates JSON-stat from JSON-stat
- sdmx2jsonstat - converts SDMX(JSON) into JSON-stat - convert OECD, UN and IMF API-data to JSON-stat
For JSON-stat eksempler i Javascript, se: https://observablehq.com/@jsonstat, https://github.com/badosa og https://bl.ocks.org/badosa
Lenker til klassifikasjoner og variabeldefinisjoner
I JSON-stat datasettene lenker vi til en klassifikasjon slik: {"Kjonn": "urn:ssb:classification:klass:2"}. Tallet til slutt er en ID slik at urn:ssb:classification:klass:2 - kan omskrives til: https://www.ssb.no/klass/klassifikasjoner/2
eller denne adressen i Klass API: http://data.ssb.no/api/klass/v1/classifications/2
Variabeldefinisjoner angis i JSON-stat på formen {Kostnadsart: "urn:ssb:conceptvariable:vardok:1116"} der 1116 er en ID. Denne kan omskrives til https://www.ssb.no/a/metadata/conceptvariable/vardok/1116/nb. /nb angir språk. Verdien kan være enten nb, nn eller en. Legger du til /xml etter /a får du XML.
Eksempler på kode for bruk av API-et
Se https://github.com/janbrus/ssb-api-python-examples/tree/master/PxWebApi2 for enkle kodeeksempler som bruker PxWebApi 2.0.
Kontakt
Kontakt statistikkbanken@ssb.no om du har spørsmål til tabellene eller API-et.
Det er også mulig å gi tilbakemeldinger på GitHub: