Et API er en softwareløsning, der ved hjælp af programmering kan automatisere processen, når du henter statistiske data og metadata fra STARs databank. Når du henter data via API’et sker det ved, at du sender en forespørgsel (et kald) til api.jobindsats.dk, hvor du beder systemet om at sende dig bestemte data. Du kan lave API-kald direkte fra Excel, Power BI og andre applikationer.

Bemærk: API’et er case sensitive. Det betyder, at kald skal matche præcis den kombination af store og små bogstaver, som den angivne API-adresse (endpoint) kræver. Brug af forkert store/små bogstaver vil medføre, at kaldet fejler. Kaldene til API’et kan sendes som POST eller GET.

De vigtigste funktioner

Du kan hente forskellige data fra API’et med følgende Kald:

1.  Hent emner i databanken – her kan du hente en oversigt over de emner, som databanken er bygget op omkring (https://api.jobindsats.dk/v3/subjects?format=json)

2.   Hent målinger under de forskellige emner - her kan du blandt andet se alle de målinger, der er i databanken (https://api.jobindsats.dk/v3/tables?format=json)

3.     Hent specifikationer for en specifik måling – disse specifikationer kan du bruge til at designe dit datakald (https://api.jobindsats.dk/v3/table/<table_id>?format=json)

4.   Hent data fra databanken - her kan du få leveret de egentlige tal fra målingerne i databanken (https://api.jobindsats.dk/v3/data/<table_id>?format=json)

Formater

Når du henter data, kan du få det leveret i to formater: JSON og CSV. Det er obligatorisk at angive det ønskede format i kaldet.

OBS! Eksemplerne i denne vejledning henter data i JSON, men hvis du ønsker resultatet i CSV, kan du blot rette ''json'' til ''csv''.

Med det første kald kan du få en oversigt over alle emner og underemner i databanken, og hvordan de er grupperet. Det giver et billede af, hvilke områder du kan finde data indenfor på Jobindsats.dk.

Du henter oversigten over emner og deres gruppering med dette kald: https://api.jobindsats.dk/v3/subjects?format=json

Her får du en oversigt over alle emner og deres underinddeling i databanken på Jobindsats.dk. Et eksempel på et overordnet emne er ''Ydelser'', mens underemner kan være ''A-dagpenge'' og ''Kontanthjælp''. Alle emner har et id (subject_id), som du kan bruge til at begrænse data, hvis du bruger Kald 2.

Med dette kald får du information om de enkelte målinger i databanken på Jobindsats.dk. Du kan få information om følgende: 

• En oversigt over de enkelte målinger under et overordnet emne eller et underemne, herunder målingens id (fx y01a02)
• Hvilke målingsvariable de enkelte målinger kan opgøres for - fx antal personer, antal fuldtidspersoner og fuldtidspersoner i pct. af arbejdsstyrken
• Seneste og næste opdateringsdato for målingen
• Første og seneste periode, som der aktuelt er data for i målingen
• Målingens periodetyper – fx år, måned, kvartal, rullende år eller år til dato
• Opdateringsfrekvens
• Dimensioner (fordelingsvariable) – fx køn, alder, herkomst, ydelse
• Link til infoside og link til målingen på Jobindsats.dk

Med dette kald får du dermed et detaljeret indblik i data i de forskellige målinger.

Du henter indhold om målingerne under de forskellige emner med dette kald: https://api.jobindsats.dk/v3/tables?format=json

Hvis du ikke ønsker informationer om samtlige målinger i databanken, kan du lave en betinget forespørgsel, hvor du bruger et subject_id fra Kald 1.

Eksempel: https://api.jobindsats.dk/v3/tables?subject_id=1123&format=json

Her henviser id’et til a-dagpenge, og der hentes dermed oplysninger for de målinger, der ligger under emnet A-dagpenge.

Inden du kan hente data fra databanken, skal du bruge en række informationer om den pågældende måling, som du ønsker at hente data fra.

Du henter informationer om den ønskede måling med dette kald:
https://api.jobindsats.dk/v3/table/<table_id>?format=json

Her skal du angive målingens id (fx y01a02). Id’et finder du i Kald 2.

Dette kald returnerer specifikationer for målingen, fx

• Målingsvariable (og eventuelle underliggende variable, hvis der er samlet flere opgørelser under én målingsvariabel), fx ”Antal personer”
• Dimensioner, fx køn, alder eller område
• Hierarkier (hierarchy) og niveauer (levels) til dimensionerne
• Periodetyper og deres udfald
• Om dimensionen er obligatorisk eller skjult for en given måling

Disse informationer skal du bruge til at designe dit datakald (jf. Kald 4 nedenfor).

Eksempel: https://api.jobindsats.dk/v3/table/y01a02?format=json

Her henviser id’et til målingen ''Antal personer og fuldtidspersoner'' for A-dagpenge, og der hentes dermed specifikationer for denne måling.

Du kan hente alle offentligt tilgængelige data fra databanken gennem API’et.

Du henter data fra databanken med dette grundlæggende kald:
https://api.jobindsats.dk/v3/data/<table_id>?period.<periodetype_id>=<period_id>&hierarchy.<hierarchy_id>=<value_id>&mgroup.<mgroup_id>=<measure_id>&format=<format>

Her skal du erstatte table_id med id’et på den måling, som du vil hente data for (det finder du via Kald 2).

Derudover skal du altid tilføje følgende obligatoriske parametre:

1. Område(r) – fx om du vil have data for specifikke kommuner, hele landet eller regioner
2. Periode(r)

Parametre tilføjes efter spørgsmålstegnet (?) og nye parametre adskilles med et &-tegn. Et eksempel på en parameter er en dimension i målingen (fx kommune, alder eller køn), men også formatet (json eller csv), ønskede målingsvariable (fx antal fuldtidspersoner eller antal personer) og periode (fx hvilke måneder du ønsker data for). 

Hvis

Du skal altid angive, hvilke målingsvariable du vil have data for. Det gør du ved at tilføje parameteren: mgroup. og de respektive mgroup_id’er samt measure_id’er.

Du kan finde id’erne for målingsvariable i Kald 3 under ''mgroups'' og ''measures''.

Eksempel:

https://api.jobindsats.dk/v3/data/y01a02?mgroup.mgrpa02_1=measa02_1&mgroup.mgrpa02_3= measa02_3&period.M=2022M06,2024M05&hierarchy._nykom=/100/,/&format=json

Her hentes data for målingsvariablene mgrpa02_1 ''Antal personer'' og mgrpa02 ''Antal fuldtidspersoner''.

Du kan hente alle målingsvariable for en måling ved at skrive ''mgroup.*=* ''

Når du henter data, kan du vælge, hvordan tallene skal fordeles.

Eksempler på dimensioner, som målinger kan fordeles på:

• Område
• Køn
• Alder
• Visitationskategori  
• A-kasse

Hierarkier
Hver dimension har et hierarki, som skal bruges i datakaldet til at angive, hvilke udfald, der ønskes fra dimensionen. Hierarkiet angiver yderligere en opdeling af data, hvis der er flere niveauer (levels) i dimensionen, det er beskrevet i næste afsnit.

Som udgangspunkt har hver dimension ét hierarki undtagen område, som har tre hierarkier: _region (regioner), _nykom (kommuner) og _reko (både regioner og kommuner). Hver af disse tre hierarkier har derudover et eller flere levels (niveauer). Fx har _region ét level, mens _reko har to levels nemlig nykom og region. 

Du kan se hierarkier (og deres id’er) for de enkelte dimensioner i Kald 3. Her kan du også se id’er for de ønskede udfald (value_id). Her vil kommune have 98 udfald, mens køn vil have 2 udfald. Value_id er en kode for et specifikt udfald inden for et givent hierarki. Value_id for kvinder i hierarkiet _kon er fx /1/.

Hvis du vil hente data for Aarhus og Region Midtjylland skal du tilføje ''hierarchy._reko=/73/92/,/73/'' til dit kald. _reko er hierarkiet for ''Kommuner og regioner'', mens /73/92/ er value_id for Århus og /73/ er value_id for Region Midtjylland.

Du kan hente alle udfald for et givent hierarki ved at angive ''*'' i stedet for de specifikke level_id’er. Alle kommuner kan hentes ved at tilføje ''hierarchy._nykom=*'' til kaldet.

Nedenfor ses et eksempel, som vil returnere alle udfald for fordelingsvariablen 'Alder' i Aarhus for målingen ''Antal personer på dagpenge''.

Eksempel:

https://api.jobindsats.dk/v3/data/y01a02?mgroup.mgrpa02_1=measa02_1&period.M=2025M02&hierarchy._reko=/73/92/&hierarchy._aldera=*&format=json 

Vil du derimod kun se data for antal personer +65 år skal du lave følgende kald:

https://api.jobindsats.dk/v3/data/y01a02?mgroup.mgrpa02_1=measa02_1&period.M=2025M02&hierarchy._reko=/73/92/&hierarchy._aldera=/11/&format=json

Hvert hierarki er yderligere inddelt i niveauer (levels). De fleste hierarkier vil kun have ét level, men når der er flere levels, kan du hente alle udfald inden for et givent level ved at tilføje ''hierarchy.<hierarchy_id>= level:<level_id>'', som en parameter til forespørgslen.

Hierarkiet for regioner og kommuner (reko) har to niveauer (levels): Et niveau for kommuner og et niveau for regioner. Alle kommuner kan således hentes ved at tilføje ''hierarchy._reko=level:nykom'' til forespørgslen.

Nedenfor ses et andet eksempel, som vil returnere alle udfald for det øverste niveau i fordelingsvariablen 'Alder' til målingen.

Eksempel:

https://api.jobindsats.dk/v3/data/y07c02?mgroup.*=*&period.M=2024M01&hierarchy._nykom=*hierarchy._tilb_2ptv= level:tilb_1ptv&format=json

Du finder antallet af levels og level_id for det ønskede niveau i Kald 3 for den givne måling.

Nogle dimensioner er obligatoriske. Hvis en dimension i Kald 3 har værdien ''is_required=1'', skal den angives i datakaldet. Det vil sige, at du skal tilføje hierarkiet for dimensionen og det/de ønskede udfald.

Nedenfor er et eksempel fra målingen ''Antal arbejdsfordelinger'', hvor fordelingsvariablen ''Arbejdsfordelingstype'' (hierarchy_id=_var13uger) er obligatorisk:

Eksempel:

https://api.jobindsats.dk/v3/data/y25i06?mgroup.*=*&period.M=2025M02&hierarchy._reko=level:region&hierarchy._var13uger=/2/&format=json

Nogle dimensioner er både obligatoriske (''is_required=1'') og skjulte (''is_selectable=0''). Det vil også fremgå i Kald 3. Her kan du ikke vælge specifikke udfald – du skal i stedet tilføje ''hierarchy.<hierarchy_id>=*'' til datakaldet for at hente alle udfald.

Nedenfor er et eksempel fra målingen ''Beskæftigede udenlandske statsborgeres arbejdsmarkedsstatus over tid'', hvor fordelingsvariablen ''Population af beskæftigede udenl. Statsborgere'' (hierarchy_id=_popbeskudl) er obligatorisk og fordelingsvariablen ''Arbejdsmarkedsstatus'' (hierarchy_id=_ams_status) er både obligatorisk og skjult.

Eksempel:

https://api.jobindsats.dk/v3/data/y24j?mgroup-*=*&period.M=2024M02&hierarchy._region=*&hierarchy._popbeskudl=/3/&hierarchy._ams_status=*&format=json

Du skal altid angive, hvilke perioder du vil hente data for. Det gør du ved at tilføje parameteren: periode. Du kan se periodetyper og udfald i Kald 3.

Du kan enten hente specifikke perioder eller de N (antal) seneste perioder. I begge tilfælde starter du med at skrive ''period.<periodetype>=<parameter-værdi>''.

Hvis du ønsker at efterspørge specifikke perioder, skrives period_id efter lighedstegnet. 

Eksempel:

https://api.jobindsats.dk/v3/data/y01a02?mgroup.*=*&period.M=2022M06,2024M05&hierarchy._nykom=/100/,/&format=json

Hvis du ønsker at efterspørge de seneste N perioder skrives ''latest:<N>'' efter lighedstegnet.

Eksempel:

https://api.jobindsats.dk/v3/data/y01a02?mgroup.*=*&period.M=latest:10&hierarchy._nykom=/100/,/&format=json

Det er ikke muligt at hente alle perioder, ved at bruge ''*''. Du skal derfor beslutte, hvilken periode du ønsker.

Hvis der er fejl i dit kald, returnerer API’et en fejlbesked.  

Hvis fejlen skyldes, at du mangler at specificere noget, eller har angivet noget forkert, får du en fejlbesked, som kan hjælpe dig videre. Hvis fejlen i stedet fx skyldes manglende serverforbindelse, eller at du efterspørger for mange celler, vises en standard-fejl.

For at få vist fejlbeskeden, som skyldes misspecifikation af kaldet, skal du muligvis lave en opsætning i din klient (det system, som du henter data til med API’et), hvor du beder om at få den vist.

Alternativt vil du få vist fejlen 422.

• Der bliver orienteret om ændringer til målinger på Jobindsats.dk, som kan være relevante for især datakald. Det kan fx være opdatering af dimensioner til målinger, eller hvis målinger fjernes midlertidigt fra Jobindsats.dk.
• API kaldet er case sensitivt. Kald skal matche kombinationen af store og små bogstaver.
• Level_id’er kan ændre sig, hvis dimensionen opdateres. Det gælder fx for level_id’erne for stillingsbetegnelser, som opdateres årligt.
• Du kan maksimalt hente cirka 1.000.000 celler per kald.

Autentificering via Bearer token
API’et anvender Bearer-baseret autentificering.

Et Bearer token er en sikker adgangsnøgle, som identificerer dig over for API’et. Tokenet sendes med i hver forespørgsel og giver adgang til de data og funktioner, du er autoriseret til at bruge. Det fungerer som en digital nøgle – den, der “bærer” tokenet, får adgang.

Ved hver HTTP-forespørgsel skal der angives en Authorization-header med et gyldigt Bearer token:

Authorization: Bearer <dit_api_token>