Generelt om Web API'et

Nyttig viden om DAWA-API'et som gælder på tværs af ressourcer.

⚠ Bemærk!
DAWA anvender tilbagekonverteret BBR-data, som ikke længere opdateres fra 16. december 2023.
BBR-data udfases helt i DAWA pr. 1. april 2024. Læs mere her.

Baseadresse

Som DAWA's baseadresse bør anvendes https://api.dataforsyningen.dk.

Dataformater

Alle typer data kan returneres i følgende formater:

Derudover understøttes også GeoJSON for de entiteter hvor det giver mening:

https://api.dataforsyningen.dk/kommuner/0101?format=geojson
https://api.dataforsyningen.dk/adresser?postnr=8830&vejnavn=Bakkevej&format=geojson

Vejstykker og adgangsadresser supporterer endvidere GeoJSON med højdeangivelse (z-koordinatet). Hvis man ønsker dette anvendes format=geojsonz:

https://api.dataforsyningen.dk/vejstykker?navn=Borgergade&format=geojsonz

Svar-strukturer

DAWA giver mulighed for at vælge om der ønskes en flad eller en nestet svarstruktur. Default er nestet for JSON og flad for GeoJSON. Struktur parameteren anvendes til at angive valget.

For at hente JSON i en flad struktur anvendes struktur=flad:

https://api.dataforsyningen.dk/kommuner/0101?struktur=flad

For at hente GeoJSON med en nestet properties struktur anvendes struktur=nestet:

https://api.dataforsyningen.dk/kommuner/0101?struktur=nestet&format=geojson

Nogle ressourcer understøtter også en særlig mini-struktur, som indeholder de vigtigste felter. Det gælder eksempelvis adgangsadresser:

https://api.dataforsyningen.dk/adgangsadresser?struktur=mini&per_side=10

Download i browser

Parameteren download tilføjer en Content-Disposition header til svaret, som får en browser til at gemme svaret som en fil fremfor at vise den:

https://api.dataforsyningen.dk/kommuner?format=csv&download

Filnavnet, som browseren benytter kan konfigureres ved at angive en værdi for download parameteren:

https://api.dataforsyningen.dk/kommuner?format=csv&download=filnavn.csv

Parametervalidering

DAWA accepterer som udgangspunkt ukendte parametre. Derfor returneres ikke nogen fejl, hvis klienten ved en vejl anvender et forkert navn til en parameter. Tilføj parameteren "valider" for at modtage enfejl hvis der anvendes ukendte parametre. Eksempel:

https://api.dataforsyningen.dk/adgangsadresser?regionkode=1084&valider

Tidsformat

Tidspunkter returneres i to forskellige formater, som begge er specificeret i Date and Time on the Internet: Timestamps. Det drejer sig om Coordinated Universal Time (UTC) og Unqualified Local Time. Vi havde foretrukket ét format, nemlig UTC, men da det ikke er alle vore datakilder, som kan leverer dette, har vi været nød til anvende to. UTC har formen: 2000-02-05T12:00:00.000Z. Unqualified Local Time har formen: 2009-02-11T09:56:50.000.

Tekstsøgning

Det er muligt at foretage en tekstsøgning i mange af de datatyper, som DAWA udstiller. Til dette anvendes query-parameteren q. For tekstsøgning gælder følgende:

  • Der er ingen forskel på store og små bogstaver
  • Der foretages såkaldt Stemming af ordene i en fritekstsøgning
  • Hvis der angives flere ord i en søgning skal alle ordene matche.
  • Accenter normaliseres, der er ingen forskel på é og e.
  • æ, ø og å normaliseres, der er ingen forskel på å og Aa.
  • Det er muligt at tilføje et wildcard '*' i slutningen af hvert ord. Wildcard matcher alle endelser.
  • Tegn, som ikke er bogstaver eller et wildcard i slutningen af et ord fortolkes som mellemrum.
  • Tekstsøgning kan kombineres med andre søgeparametre. Se mulighederne under dokumentationen for de enkelte APIer.
  • Ved anvendelse af tekstsøgning returneres maximalt 1000 instanser.

Hvis behovet er at fremsøge en enkelt adresse eller adgangsadresse ud fra en adressetekst vil det i de flestetilfælde være bedst at benytte datavask API'et..

Eksempler

Find de adresser som matcher Lilledal 1

https://api.dataforsyningen.dk/adresser?q=Lilledal 1

Find alle vejnavne, som starter med vibor

https://api.dataforsyningen.dk/vejnavne?q=vibor*

Find alle vejnavne i Aarhus kommune (kommunekode 751), som starter med vibor

https://api.dataforsyningen.dk/vejnavne?q=vibo*r&kommunekode=751

Autocomplete

DAWA udstiller API'er til autocomplete af de fleste entiteter.

Autocomplete har samme egenskaber som tekstsøgninger beskrevet ovenfor, med følgende forskelle:

  • Der tilføjes automatisk et wildcard til det sidste ord i søgningen, med mindre det sidste tegn i søgestrengen er et mellemrum
  • Autocomplete returnerer en liste af simple forslag. Hvert forslag indeholder et 'tekst' felt, som beskriver forslaget, samt et objekt med oplysninger der identificerer forslaget.
  • Der returneres som udgangspunkt 20 resultater. Ønskes et andet antal anvendes per_side parameteren.
  • Der understøttes kun formaterne json, jsonp og ndjson. CSV er ikke understøttet.

For adgangsadresser og adresser tilbyder DAWA også et kombineret autocomplete APImed tilhørende javacript klientbibliotek, som giver en bedre brugeroplevelse til adresseindtastning.

Eksempler

Find de adresser som matcher Lilledal 1

https://api.dataforsyningen.dk/adresser/?q=Lilledal 1

Find alle vejnavne, som matcher vibor

https://api.dataforsyningen.dk/vejnavne/autocomplete?q=vibor

Find alle vejnavne i Aarhus kommune (kommunekode 751), som matcher vibor

https://api.dataforsyningen.dk/vejnavne/autocomplete?q=vibor&kommunekode=751

Versionering

DAWA ændres med tiden pga. nye ønsker, fejlrettelser, nye data, ændring af de bagvedliggende data osv. Vi ønsker af flere grunde ikke at have flere versioner af DAWA i drift samtidigt. Vi ønsker heller ikke, at de klientprogrammer, som anvender DAWA, holder op med at fungere, når DAWA opdateres. For at undgå for mange forskellige versioner af DAWA og undgå at klientprogrammer fejler, når DAWA opdateres, overholder vi følgende verioneringsprincipper:

  • Det er tilladt at tilføje noget til API'et. Nye ressourcer, nye data, nye søgeparametre mm.
  • Det er ikke tilladt at fjerne noget fra API'et.

Hvis en opdatering af DAWA ikke kan overholde ovenstående principper etableres en ny version, som i en periode driftes samtidig med den tidligere version. Nedlæggelse af aktuel version med information om skift til ny version varsles 1 år før.

Det er vigtigt, at de klientprogrammer, som anvender DAWA, er robuste over for de ændringer af API'et, som er tilladt i forhold til ovenstående principper. Det, der ofte skaber de største problemer, er nye dataelementer i en datastruktur. Her er det vigtigt at vælge de teknikker, som kan håndtere dette. Klientprogrammer skal kunne håndterer nye name/value par i JSON. Nye kolonner i CSV. Hvis Klientprogrammerne er robuste over for det, vil de fejlfrit kunne fungere når DAWA opdateres indenfor en version.

Kompression

Hvis den anvendte netværksforbindelse er langsom (lille båndbredde) og den datamængde der ønskes fra DAWA er stor, kan klientapplikationen anmode om at svaret (response) komprimeres. Dette gøres ved at indsætte følgende http header i requestet.

Accept-Encoding: gzip, deflate

Herved reduceres størrelsen af et typisk response med ca. 90%.

Cross Origin Resource Sharing

Alle GET svar fra DAWA indeholder en CORS header der tillader cross-site requests:

Access-Control-Allow-Origin: *

Dette muliggør cross-site requests direkte til DAWA.

Caching

Som udgangspunkt caches svar fra DAWA i 24 timer, dvs. at de data der returneres fra DAWA kan være op til 24 timer gamle. Ønskes der helt friske data tilføjes query parameteren cache=no-cache.

Paginering

Det er ikke altid formålstjenligt at hele resultet returneres på en gang. Til tider er fordelagtigt at opdele resultatet i mindre bidder. Det kaldes paginering - opdeling i sider. Det gøres ved at angive en sidestørrelse (per_side) samt et sidenummer (side) i requestet. Nedenstående Grøndal sogn request returnerer side 3 med en sidestørrelse på 24 adresser per side.

https://api.dataforsyningen.dk/adresser?sogn=7060&side=3&per_side=24

Af tekniske årsager er det ikke muligt at understøtte paginering i det fulde adressesæt. P.t. er det muligt at paginere i de første 400.000 adresser. Denne grænse kan blive reduceret yderligere.

Såfremt man ønsker at få adressesættet delt op i flere mindre dele og hente hver enkelt del i en separat HTTP forespørgsel, så anbefales det, at hente listen af sogne først, og dernæst hente adresserne for hvert sogn.

Fejlhåndtering

Følger Problem Details for HTTP APIs

Eksempel på returneret fejlbeskrivelse:

{
  "type": "ResourceNotFoundError",
  "title": "The resource was not found",
  "details": {
    "id": "0254b942-f3ac-4969-a963-d2c4ed9ab943"
  }
}

Formatering

Web API'ets svar i JSON er formateret. Hvis formatering af f.eks. performancegrunde ikke ønskes, så kan parameteren noformat anvendes, som vist i eksemplet nedenfor:

https://api.dataforsyningen.dk/adresser?sogn=7060&vejnavn=Hvidkildevej&noformat

Flerværdisøgning

En række parametre understøtter flerværdisøgning, hvor søgeværdierne er adskilt vha. pipe ('|').Se hvilke parametre som understøtter flerværdisøgning i dokumentationen for de specifikke API'er.
Hvis man f.eks. ønsker alle adresser med husnummmer 177 i både Københavns og Frederiksberg kommune gøres det på følgende måde:

https://api.dataforsyningen.dk/adresser?kommunekode=0101|0147&husnr=177

Søgning efter ingen værdi

En række parametre understøtter søgning med match på ingen værdi.Se hvilke parametre som understøtter søgning efter ingen værdi i dokumentationen for de specifikke API'er.
Søgning angives som en normal query parameter, men med den tomme streng som værdi.
Hvis man f.eks. ønsker alle adresser på Gammel Kongevej 177 der ikke har angivet en etage gøres det følgende måde:

https://api.dataforsyningen.dk/adresser?vejnavn=Gammel%20Kongevej&husnr=177&etage=