Privatlivs- & Cookiepolitik

Vi bruger cookies for at give dig som bruger den bedst mulige oplevelse på dst.dk. Ved at fortsætte på siden accepterer du vores brug af cookies.

OK

Læs mere om vores Privatlivs- & Cookiepolitik her

Statistikbank API - Beta

Indholds­fortegnelse

Konsol
Generelt
Funktion
Sprog
Format
Tabeller og emner
Metadata og data
BETA-ændringslog

Med Danmarks Statistiks API til Statistikbanken, er det muligt programmatisk at tilgå alle publicerede data i Statistikbanken..

Konsol

Vi har stillet en konsol til rådighed, hvor det er muligt at prøve sig frem med API’et.

Konsollen er et manuelt redskab til programmører, som ønsker at anvende API’et. Den kan hjælpe programmøren med at finde frem til, hvordan API’et skal kaldes. Konsollen er på dansk, hvis browseren har dette som foretrukne sprog, ellers på engelsk.

Start konsol

Generelt

Forespørgsler sendes til den ønskede funktions url og de nødvendige informationer POST’es som et JSON-objekt.

Al kommunikation skal som udgangspunkt foregå i UTF-8.

API’et kan svare i hhv. JSON eller XML. For DATA-kaldet gælder andre og flere returformater.

Det er muligt at angive parametre i url’en, men det anbefales at POST’e data. Ved angivelse af indstillinger i URL’en (GET), skal oplysningerne url-encodes. Se eksempler i konsollen.

API’ets adresse er http://api.statbank.dk

Funktion

Der skal altid angives versionsnummer samt navnet på den ønskede funktion:
http://api.statbank.dk/v1/subjects
http://api.statbank.dk/v1/tables
http://api.statbank.dk/v1/tableinfo
http://api.statbank.dk/v1/data

Sprog

Som udgangspunkt svarer API’et på dansk. Sproget kan for alle kald angives med en parameter:

{
   "lang": "en"
}

Der kan angives enten "da" for dansk eller "en" for engelsk.

API’et vil i visse tilfælde returnere fejlmeddelelser på både dansk og engelsk, hvis fejlen har resulteret i manglende bestemmelse af sprog.

Format

For alle andre funktioner end DATA, kan formaterne JSON eller XML angives:

{
   "format": "JSON"
}

Tabeller og emner

Der er to måder at finde frem til tabeller via API’et.  Funktionerne SUBJECTS og TABLES.

SUBJECTS

Funktionen SUBJECTS tilgår det hierarki af emner, hvori alle tabeller er placeret. Hierarkiet kan tilgås ét eller flere niveauer ad gangen.

Hvis funktionen kaldes uden angivelse af parametre, returneres øverste niveau i hierarkiet. Herefter kan disse emners underemner findes ved igen at kalde SUBJECTS med angivelse af de ønskede emner og så fremdeles.

Der kan angives flg. funktionsspecifikke parametre:

{
   "subjects": [
      "02",
      "2401"
   ],
   "includeTables": true,
   "recursive": true
}

subjects: Emner for hvilke, der ønskes underemner.

includeTables: Hvorvidt resultatet skal indeholde tabeller. I modsat fald returneres kun emner, og tabeller kan efterfølgende hentes med funktionen TABLES.

recursive: Hvorvidt emners underemner/tabeller skal hentes hele vejen ned gennem hierarkiet. I modsat fald hentes kun nærmeste niveau under de angivne emner.

TABLES

Funktionen TABLES returnerer tabeller filtreret efter bestemte kriterier. Hvis der ikke angives nogle kriterier, returneres alle tabeller.

Der kan angives flg. funktionsspecifikke parametre:

{
   "subjects": [
      "02",
      "2401"
   ],
   "pastdays": 1,
   "includeinactive": true
}

subjects: Emner fra hvilke der skal returneres tabeller. Emnekoder hentes med funktionen SUBJECTS.

pastdays: Antal af dage indenfor hvilke returnerede tabeller skal være opdateret.

includeInactive: Hvorvidt der skal returneres tabeller, som ikke længere opdateres.

Metadata og data

En tabel består af metadata og data.

Metadata er informationer om bl.a. tabellens titel samt enheden for data. For visse data-formater, fx CSV, er disse informationer kun tilgængelige i metadata, hvorfor disse bør læses i forbindelse med hver læsning fra tabellens data.

For andre formater, fx Excel eller graf (PNG), indeholder selve data også information om fx titel og enhed. Det kan dog stadig være en god idé at læse metadata, for fx at se en eventuel note til data.

TABLEINFO

Funktionen TABLEINFO returnerer metadata for en tabel. Svaret indeholder information om variable og disses koder i tabellen. Det er disse koder, der skal anvendes, når data efterspørges med funktionen DATA.

Der skal altid angives tabel:

{
   "table": "folk1c"
}

DATA

Funktionen DATA returnerer data fra en tabel.

API’et forsøger at eliminere de af variablene, der ikke er valgt værdier for. Hvis der fx ikke vælges område i tabellen FOLK1C, returneres data for hele landet.

For de variable der ikke ønskes elimineret, angives variablen ved dennes kode samt koderne for de værdier, der ønskes. Koder for variable og værdier findes via funktionen TABLEINFO.

Fx har tabellen FOLK1C’s variabel ”oprindelsesland” koden ”ieland”, og værdien ”Danmark” for denne variabel har koden ”5100”. Hvis der ønskes data for de observationer, hvor oprindelsesland er Danmark, angives:

{
   "table": "folk1c",
   "format": "CSV",
   "variables": [
      {
         "code": "ieland",
         "values": [
            "5100"
         ]
      }
   ]
}

For værdier kan angives ”*” som jokertegn, sådan at ”*” betyder alle værdier, og fx ”*K1” betyder alle koder, der ender med ”K1”.

Nogle tabeller indeholder variable, som ikke kan elimineres automatisk. Der skal altid vælges værdier for disse. Dataformater der streames, tillader slet ikke elimination af variable.

En sum angives som fx "sum(0-4;5-9;10-14;15-19;20-24)", hvilket returnerer en sum af de angivne koder. Summen kan tilføjes en tekst: "sum(0-24 år=0-4;5-9;10-14;15-19;20-24)" og en kode: "sum(0_24|0-24 år=0-4;5-9;10-14;15-19;20-24)". Hvis samme forespørgsel bruges til at trække data i forskellige sprog, kan det være nyttigt at tilføje specifikke tekster for hvert sprog: "sum(0_24|[da 0-24 år][en 0-24 years]=0-4;5-9;10-14;15-19;20-24)".

Der kan angives sekvenser af koder ved en før/lig/efter-betingelse. Perioden 1. kvt. 2010 til 4. kvt. 2015 kan fx angives ved ">=2010K1<=2015K4". Betingelsen kan angives med eller uden "=" og kan kombineres med andre valg for samme variabel. Bemærk at de enkelte valg ikke har indflydelse på hinanden. Derfor vil ">=2010K1" og "<=2015K4" angivet hver for sig give hhv. alle værdier fra og med 2010K1 samt alle værdier til og med 2015K4, hvilket i praksis er alle variablens værdier.

Perioder returneres sorteret (enten stigende eller som angivet i timeOrder) uanset i hvilken rækkefølge, de er angivet i forespørgslen, ligesom dubletter automatisk frasorteres. Perioder kan, ligesom andre variables værdier, angives ved deres kode inkl. evt. brug af joker-tegnet "*". Der kan derudover anvendes nth-regler til angivelse af perioder. Nth-regler skal altid omkranses af parentes. Foranstillet +/- eller first/last bestemmer fra hvilken ende af perioderne, der tælles. Seneste tre perioder kan fx angives (-n+3). Ældste tre perioder -(-n+3), nyeste periode (1), næst-nyeste periode (2), næstældste periode -(2) etc. Koder og regler kan blandes i en kommasepareret liste. Nth-reglen fungerer ligesom css-selectoren beskrevet på http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#nth-child-pseudo.

Hvis der ikke angives en ønsket periode, returneres data for seneste periode i tabellen svarende til at angive "(1)".

Der er flg. funktionsspecifikke parametre, hvoraf table og format altid skal angives.

{
   "table": "folk1c",    "format": "CSV"    "valuePresentation": "Default",    "timeOrder": "Ascending",    "variables": [       {          "code": "OMRÅDE",          "placement": "stub",          "values": [             "000",             "185",             "791",             "787"          ]       },       {          "code": "KØN",          "values": [             "*"          ]       },       {          "code": "Tid",          "values": [             "2010k2",             "(1)"          ]       }    ] }

table: Tabel der skal hentes data fra.

format: Format data ønskes returneret i. Se afsnittet Data-formater.

valuePresentation: Hvordan tekster skal vises. Parameteren kan udelades, eller der kan angives en af flg. værdier:
Default, Code, Value, CodeAndValue eller ValueAndCode

timeOrder: Rækkefølge for perioder angivet som ascending eller descending.

variables: Samling af variabel-objeker med angivelse af dennes kode samt koderne for de ønskede værdier. I eksemplet hentes data for områderne Hele landet (000), Tårnby (185), Viborg (791) og Thisted (787), for alle køn (*) for perioden 2. kvartal 2010 (2010K2) samt nyeste periode ((1)). Det er desuden angivet, at variablen område skal placeres i tabellens forspalte (angives som hoved (head) eller forspalte (stub)).

Data-formater

For DATA-funktionen kan flg. data-formater vælges:

PX : PC-Axis (ANSI)
CSV: Semikolonsepareret
JSONSTAT: JSON-stat
DSTML: Statistikbankens XML-format
PNG: Graf som billede (se beskrivelse nedenfor)
AREMOS: AREMOS

Flg. er streaming-formater, som beskrives nedenfor:
BULK: Semikolonsepareret fil
SDMXCOMPACT: SDMX-ML Compact
SDMXGENERIC: SDMX-ML Generic

Flg. er præsentationsformater, for hvilke det gælder, at der kan laves småændringer i produktionsmiljøet, selvom systemet ikke skifter versionsnummer:
XLSX: Excel
HTML: HTML

Særlige dataformater

PNG

Data kan returneres som en graf. For dette format kan der angives en række parametre, der angiver, hvordan grafen præsenteres i den returnerede billedfil.

{
   "table": "folk1c",
   "format": "PNG",
   "variables": [
      {
         "code": "køn",
         "values": [
            "1",
            "2"
] } ], "chartsettings": { "type": "column", "width": "900", "height": "400", "showlegend": "true", "showtitle": "true", "fontsize": "13", "sort": "false", "autopivot": "true", "labelsangle": "0",
"titlecolor": "ff000000",
"seriescolors": [ "00ff00", "0000ff" ], "valuecolors": [ "2ff0000" ] } }

I eksemplet trækkes data fra tabellen FOLK1C. Værdierne Mænd (1) og Kvinder (2) vælges for variablen Køn. Der angives endvidere en række indstillinger vedrørende grafens præsentation:

type: Graf-type i hvilken data ønsket præsenteret. Der kan angives flg. værdier:
Line, Column, StackedColumn, StackColumn100, Bar, StackedBar,
StackedBar100, Area, StackedArea, StackedArea100, Pie, ColumnAndLines, Population.

width: Billedets bredde i pixels.

height: Billedets højde i pixels.

Ved ændring af størrelsen skaleres billedet ikke blot. Selve grafens udformning bestemmes af den til rådighed værende plads.

showlegend: Hvorvidt billedet skal indeholde en boks med angivelse af serie-tekster.

showtitle: Hvorvidt billedet skal indeholde tabellens titel og undertitel.

fontsize: Skriftstørrelse.

sort: Hvorvidt observationerne skal sorteres.

autopivot: Hvorvidt variablen med flest værdier skal flyttes til label-aksen.

labelsangle: Vinkel på tekster på label-aksen.

seriescolors: Samling af farver til serier. Farver angives som fx ”ff0000” for rød. I ovenstående eksempel angives grøn og blå som de første farver, der skal anvendes til serier

valuecolors: Samling af farver til specifikke værdier. Angives ved kode efterfulgt af farve. Fx betyder ”2012K400ff00”, at 4. kvt. 2012 skal vises som grøn. I ovenstående eksempel angives, at koden 2 (Kvinder) skal vises med farven rød.

STREAMINGFORMATER

Hvis der vælges mange værdier fra en tabel, kan nogle udtræk blive for store at håndtere på serveren. Nogle udtræk kan komme op på flere milliarder celler.

Da datasæt af denne størrelse sagtens kan anvendes i fx databaser, har vi valgt at stille denne output-type til rådighed.

Resultatet adskiller sig fra de øvrige formater på en række vigtige områder:

- Nogle observationer udelades. Hvis en kombination af værdier mangler, er observationen for denne kombination 0 (tallet nul). Hvis kombinationen er repræsenteret, men tallet mangler, betyder det, at observationen mangler, er diskretioneret eller er for usikker til at kunne angives.

- Variable kan ikke udelades (elimineres) og rækkerne (værdierne) er ikke nødvendigvis sorteret i samme rækkefølge som angivet i forespørgslen.

BETA-ændringslog

Vi udvikler løbende på kildekoden for at forbedre og optimere API'et. I BETA-perioden vil disse ændringer blive publiceret, uden at API'ets versionsnummer øges.

Visse ændringer med betydning for anvendelse af API'ets output vil i denne periode blive tilføjet flg. liste.

December 2017
   - Kontaktpersoner returneres som samling.
   - Feltet SuppressedDataValue tilføjet til TABLEINFO. Værdien skal anvendes for manglende-række-observationer i streaming-formaterne.
   - Observationer for lagrede rækker med manglende værdier returneres som ".." i stedet for "".
   - Mulighed for angivelse af sekvens af koder ved før/lig/efter-betingelse.

Oktober 2017
   - HTTPS tillades. Anvend det gerne med det samme. På sigt 301-redirect'er vi alle HTTP-kald, hvorved evt. request body (POST) mistes.
   - Nu muligt at tillade flere variable i hovedet af CSV-format
   - Nu mulighed for at lade værdipræsentation tilsidesætte koder i kolonnenavne for CSV-format
   - Rettelse som løser problem, hvor tredieparts-komponent fejlede ved én periode, hvor dennes kode indeholdt "-"
   - Ændringer i backend vedr. caching af data

September 2017
   - Det tillades ikke længere at anvende en eliminationsværdi som en del af sum
   - Summers værdier kan nu adskilles med komma
   - Konsol anvender egen kopi af jQuery, for at konsollen fungerer i et lukket system, hvor der er særligt åbnet for anvendelse af konsollen

Juni 2017
   - Headers forsimples til simple tegn, da fx danske tegn medfører fejl i visse systemer
   - Korrekt overførsel af visse chartsettings ved GET

Marts 2017
   - Forbedret mulighed for cross site anvendelse
   - Grafer begrænses til maksimalt 50 serier

Januar 2017
   - Tilføjet returneret status-kode og headers til konsol
   - Tilføjet kontaktinformation til TABLEINFO

Oktober 2016
   - Tilføjet information om statistikdokumentation til TABLEINFO

Juni 2016
   - En fejl ved udtræk i JSONSTAT, når flere variable havde geo-information er rettet

April 2016
   - Tilføjet information om evt. geografisk kort for variabel (map) til TABLEINFO

Marts 2016
   - Tilføjet information om emne-status (active) til SUBJECTS

December 2015
   - Forbedret fejlmeddelelse for fejl ifm. gemte forespørgsler

Oktober 2015
   - Rettelse ifm. indholdsvariabel i JSONSTAT-format
   - Rettelse ifm. valg af værdipræsentation

Juli 2015
   - En fejl hvor periode-kode blev engelsk ved dansk udtræk af koder er rettet
   - Mulighed for elimination af en variabel ved en enkelt af dennes værdier

Juni 2015
   - Ikke længere mulighed for tekster præsenteret som værdi efterfulgt at kode

April 2015
   - Datoformatet i funktionerne SUBJECTS og TABLES stemmer nu overens med formatet i TABLEINFO
   - Restriktioner for generering af summer på visse tabeller, variable og opgørelsesmetoder
   - Der kan anvendes komma i sumerings-tekster

Marts 2015
   - Generering af summer i dataudtræk

November 2014
   - Angivelse af tider med nth-regel (a la http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#nth-child-pseudo).
   - AREMOS-format fjernet

Oktober 2014
   - Der er tilføjet kolonneoverskrifter til formaterne CSV og BULK
   - Formatet BULK kan nu vise tekster. Vælg eksplicit valuePresentaion=code, hvis koder ønskes

 

Få lavet jeres egen Statistikbank

StatHost

StatHost

Ansvarlig for siden

Web og Statistikbank