1. Jan Bruusgaard
Seksjon web og Statistikkbank
statistikkbanken@ssb.no
Api-kurs september 20171
SSBs API mot Statistikkbanken
2. www.ssb.no/api
• Innhold i kurset
• Generell oversikt over SSBs API.
• Demonstrasjon av API: Ferdige datasett
• Demonstrasjon av API-konsoll
• Lage egne spørringer i API konsoll (oppgaver)
• Bruke API for å søke tabeller i Statistikkbanken
• Ressurser for å bruke APIet
3. Statistikkbanken
• Mer enn en milliard tall
• Fordelt på 5000 tabeller
• Av dette rundt 470 tabeller på kommunenivå
• Tall tilbake til 1769
• Oppdateres (nesten) hver dag
• Tips: Snarvei til tabeller
• www.ssb.no/tabell/kortnavn
– www.ssb.no/tabell/kpi (alle KPI i Statistikkbanken)
• www.ssb.no/tabell/ 5 sifret tabell nummer
– www.ssb.no/tabell/07459
www.ssb.no/en/table/03013 (engelsk)
• Introduksjon video (2:55)
4. Hva kan en bruke SSBs API til
SSB API4
• hente data/statistikk automatisk inn i:
• Tekst
• Figur / visualisering
• Tabell
• Webapplikasjon f.eks. http://www.ssb.no/kommunefakta/oslo
• Database
• Analyseverktøy
– SAS, R etc.
5. Eksempel: Bloomberg
5
• Bloomberg sender denne nyheten:
• NORWAY MARCH TRADE SURPLUS NK9.1 BLN
• Den kan deles i to
• Mal
• Data
• NORWAY MARCH TRADE SURPLUS NK9.1 BLN
• Hvordan kan de lage denne kl. 08.00.02?
9 068Ikke –2016M03
6. Hva betyr API
6
• API: Application Programming Interface
Grensesnitt for programmering
mot en applikasjon
• Applikasjonen er Statistikkbanken
• Web API betyr web grensesnitt mot API,
benytter http - hypertext transfer protocol
• Programmere uttrekk fra banken via web
• Kan arbeide på dataelement-nivå uten at det må
opprettes lokale kopier
7. SSB har 2 API-er
SSB API7
• Ferdige datasett (lansert juni 2013)
• Lag egne datasett (kom mai 2016)
8. API er for våre storbrukere
API: Lag egne datasett (POST)
API: Ferdige datasett (GET)
Mitt SSB - lagret søk mot Statistikkbanken
Statistikkbanken
Statistikk med ferdigtabeller
Nøkkeltall
9. API: Ferdige datasett
SSB API
9
• SSB lager datasettet
• Kun 250 datasett
• Dekker mest etterspurte tabeller
• Fordel: SSB holder oversikt over endringene
• Egen adresse (URL) til hvert datasett
• http GET
• Utformat
• JSON-stat
• CSV
10. API: Lag egne datasett
SSB API10
• Dekker alle 5 000
Statistikkbanktabellene
• Fleksibelt
• Bruker definerer selv uttrekk
• Velg størrelse fra 1 til 500 000 celler
• Høyere maks. grense enn Statistikkbanken
• Velger kun variabler en har behov for
11. API: Lag egne datasett
• Består av to deler
• API: konsoll
• teste og redigere spørringer
• API: Direkte til datasettene (PX-API)
• http POST
• Poste spørring mot url
• GET for å traversere
11
13. Spørringer
• Formuleres i JSON-format
• Enkel og kompakt
• enkelt å lære grunnleggende syntaks
• POSTes mot URL
14. JSON – hva er det?
• JSON
• JavaScript Object Notation
• Har ingenting med Java å gjøre og er etter hvert uavhengig av JavaScript
• Lettvekts tekst format for datautveksling
• Enklere og erstatter mer og mer XML
• Relativt lett å lese for mennesker
• Maskiner kan lett analysere og generere JSON
• {}
14
15. Spørring - filter
• 3 filtre: item, all, top
• Item
• enkeltverdier
• All
• Trunkering *
• Bare * - velger alle
• Top
• Siste / øverste verdier
• Egnet for rullerende tid
SSB API15
16. JSON struktur
Fordi teorien er litt vanskelig for ikke-programmerere, lagde vi konsollen
• Samling av navn/verdi par
• Objekt { medlemmer }
• Kan nøstes
• Ordnet liste med verdier
• Array [ elementer ]
• Navn/verdi par
• Streng : verdi
• "filter" : "item"
16
17. API Output formater
• JSON-stat (http://json-stat.org)
• Anbefalt og forhåndsvalgt i konsoll-spørring
• egnet for statistikk - datasett i mange dimensjoner
• Ferdige bibliotek for
• Javascript
• Java
• R
• Python
• CSV (kommaseparert)
• XLSX (Excel)
SSB API17
18. Statuskoder
• Statuskoder fra API gis når en henter datasett
• 200 – ok
• 404 – feil i URL eller i syntaks på spørringen.
• 403 – sperre ved for stort datasett.
500 000 celler (inkl. tomme celler).
• 429 – for mange spørringer. Grensen er 30 i
minuttet
• 503 – time-out etter 60 sekunder
SSB API18
19. Metadata-fanen
19
Tips:
1. Prettyfy JSON
2. Klipp deler herfra og
lim inn i spørring
Alternativ: Lag spørring med filter all *
response xlsx/json-stat. Bruk
kodene her til å lage ny spørring.
20. Oppgave - konsoll
20
• Start Firefox eller Chrome.
• Hent opp tabell 07459 i konsoll. Trykk Kjør.
• Endre spørring til å
1. Ta ut dataene i Excel. Se på kodene.
2. Ta kun ut antall 0-åringer (000) begge kjønn i Halden (0101)
3. Begrense uttrekk til perioden 2010 - 2017.
• Det er flere måter å gjøre dette. Prøv å bruke filtrene:
– Item
– All
– Top
• Hvorden vil disse virke i mars 2018.
• Trykk «Kjør» mellom hvert av punktene
21. Oppgave 2 - konsoll
21
• Fortsett med tabell 07459 i konsoll. Endre
spørring til å
1. Ta ut antall 100-åringer i Halden (0101) og Oslo
(0301) i 2017 som csv
2. Endre til totalt antall innbyggere Oslo og Halden
som Excel
• Tips: Alder har elimination: true
3. Totalt antall innbyggere i Akershus fylke (02) og
alle kommuner i Akershus
• Tips: filter all
• Trykk «Kjør» mellom hvert av punktene
22. Lage et eget enkelt datasett i API?
22
• Velg API konsoll
• http://data.ssb.no/api/v0/no/console
•
•
Søk f.eks tabell 07459
• Be om Excel som utformat:
• I helt nederst i ruten for Spørring, rediger :
"format": "json-stat"
• Slik:
"format": "xlsx"
• Trykk på knappen:
24. Hva skjer framover
• Ny Statistikkbank basert på PX-web / KOSTRA
modernisering
• Lansering vinter 2018 (9. januar?)
• Mulig å få API-kode til spørringer direkte fra
Statistikkbanken
• videreutvikling PX-API som del av PX-web
• GET URL'er
• Annet
• JSON-stat 2.0
• nå har vi versjon 1.2
25. Kjente mangler
• «Foreløpige tall» vises forskjellig eller markeres ikke i
det hele tatt
• Grense på 500.000 celler, inkl tomme celler
• Statistikkvariabeltekst vises i hode sammen med tid i
CSV
• Metadata viser ikke aggregeringer og grupperinger.
Kommer i 2018?
• http GET støttes ikke. GET url-er kommer 2018?
• Dårlig informasjon om neste publisering og
oppdatering
26. Hvordan få informasjon om publisering?
• Statistikkkalenderen
http://www.ssb.no/kalender
• RSS-feeden for kommende publiseringer
http://www.ssb.no/rss/kalender
• Abonnere på nyhetsbrev: Mitt SSB
• RSS: sist oppdaterte tabeller i Statikkbanken
for et kortnavn
http://www.ssb.no/rss/statbank/kortnavn
• Den enkelte statistikkside
26
27. Ressurser
• Se Brukerveiledningen nytt API for lenker
• JSON-stat
• json-stat.org
• Se også json-stat.com/nsm – kursmateriale og verktøy
• JSON-stat Conversion Tools (command line interface) bl.a.
egnet for å lage fleksibel CSV.
• Nettleser
• Ikke bruk Internet Explorer.
• anbefalte utvidelser
• Jsonviewer
• Poster
29. Bloomberg forts.
29
• Hvilket API er raskest?
“My question is if your data will be provided on the new interface
any faster than on the old API feed. I am thinking of terms of
seconds, or even, milliseconds.”
• APIet med ferdige datasett er raskest
• Varnish cache
• 2-10 sekunder for første spørring etter kl. 8
avhengig av størrelse på datasettet.
30. API: Direkte til datasettene – via url
•
http://data.ssb.no/api/v0/no/table/
• Traversere
emnestruktur
• emne –> underemne
–> statistikk (kortnavn)
–> tabell (POST url)
• Snarvei: legg til
tabellnr. etter table
i url
SSB API30
31. Søk API med URL
• Innledes med: ?query=
• søker også variabler
• Søk med Tabellid for å finne tabellnummer:
http://data.ssb.no/api/v0/no/table/?query=folkframt6
• Søk bolig begrenset til tittelfelt
http://data.ssb.no/api/v0/no/table/?query=title:bolig
• Søk etter alder, begrenset til emnet transport
http://data.ssb.no/api/v0/no/table/tr?query=alder
31
32. Søk API med URL, forts.
• space gir AND
• Tegnene ?( … )=(…) i url gir parametre, flere
parametre kombineres med &
• ssb.no (ikke API) KOSTRA eksempel :
http://www.ssb.no/sok?innholdstype=statistikkbanktabell&sok="funksjon 170"
• http://data.ssb.no/api/v0/no/table/?query=funksjon AND 170
• Begrense til ett felt med feltnavn og kolon
?query=title:indeks
• husk at en del tabeller er på nynorsk
• Se flere eksempler i Brukerveiledningen
32
33. Oppgave 3 - søk
33
• Naviger i datastrukturen
http://data.ssb.no/api/v0/no/table/
ned til tabellen "Totalkostnadsindeksar for
lastebiltransport"
• Tips: Finn den evt. først i strukturen på ssb.no
• Finn statstikker under kriminalitet som har
variabelen statsborgerskap
34. SSBs API: Oppsummert
SSB API34
• Det nye API-et er best:
• Mest fleksibelt
• Lag egne datasett
• Størst
• 5000 tabeller,
• opptil 500.000 celler pr. spørring
• Det gamle API-et er:
• Enklest
• Ferdige datasett, men ingen Kostra-datasett
• Raskest
• Begrenset
• http://www.ssb.no/api
• Kontakt: statistikkbanken@ssb.no (evt. jbr@ssb.no)
36. cURL
• cURL – web fra kommandolinjen
• Egnet for å overføre data raskt
• egnet for API-bruk
• cURL er allerede installert på Linux
• cURL er mulig å installere på Windows
• Bruke cmd.exe eller powershell
• På Windows må alle ‘ erstattes med ‘’
36
37. cURL
• lagre spørring fra API-konsoll
filen sp1.json på hjemmeområdet på linux
• kjør cURL slik fra kommandolinjen:
• -d input
• @ les input (spørring) fra fil
• -X POST bruk http post
• -o skriv til outputfil
37
39. Klass API
• SSBs tjeneste for Klassifikasjoner og
kodelister
• https://www.ssb.no/klass
• KLASS API guide
• Alle eksempler i Klass API benytter cURL
• Source code on Github
http://github.com/statisticsnorway/klass
39
40. JSON-stat conv
• JSON-stat Conversion Tools
• https://github.com/badosa/JSON-stat-conv
• Forutsetter node.js installert
• Fleksible konverteringsverktøy
• jsonstat2csv - converts JSON-stat into CSV
• jsonstat2array - converts JSON-stat into an array of arrays
• jsonstat2arrobj - converts JSON-stat into an array of objects
• jsonstat2object - converts JSON-stat into an object
40
42. R: Lag eget datasett (POST) eksempel
• Se også MyRland http://www.myrland.one
http://www.myrland.one/2016/06/07/ssbs-api-for-a-laste-ned-bensin-og-dieseldata/
42