Generelt om Web API'et

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

Baseadresse

Som DAWA's baseadresse kan enten anvendes http://dawa.aws.dk eller https://dawa.aws.dk.

Dataformater

Alle typer data kan returneres i følgende formater:

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

http://dawa.aws.dk/kommuner/0101?format=geojson
http://dawa.aws.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:

http://dawa.aws.dk/vejstykker?navn=Borgergade&format=geojsonz

Shapefile-formatet er meget populært i GIS-kredse. Vi ville gerne have supporteret det, men DAWA's streaming af nær realtids opdaterede data passer ikke godt sammen med Shapefile-formatet. Du kan selv generer Shapefiler vha. DAWA's GeoJSON data og dit GIS-program eller ogr2ogr programmet. Du kan se eksempler på hvordan i AWS-gruppen på Digitaliser.dk.

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.

Eksempler

Find de adresser som matcher Lilledal 1

http://dawa.aws.dk/adresser?q=Lilledal 1

Find alle vejnavne, som starter med vibor

http://dawa.aws.dk/vejnavne?q=vibor*

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

http://dawa.aws.dk/vejnavne?q=vibo*r&kommunekode=751

Autocomplete

DAWA udstiller API'er til autocomplete af adresser, adgangsadresser, veje, postnumre, supplerende bynavne samt kommuner.

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.

Eksempler

Find de adresser som matcher Lilledal 1

http://dawa.aws.dk/adresser/autocomplete?q=Lilledal 1

Find alle vejnavne, som matcher vibor

http://dawa.aws.dk/vejnavne/autocomplete?q=vibor

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

http://dawa.aws.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.

http://dawa.aws.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:

http://dawa.aws.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:

http://dawa.aws.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:

http://dawa.aws.dk/adresser?vejnavn=Gammel%20Kongevej&husnr=177&etage=

Maksimalt antal samtidige requests

Der er en grænse på hvor mange samtidige requests til DAWA, der må foretages fra en enkel IP adresse. Grænsen er på 10 samtidige requests. Baggrunden for at sætte denne grænse er, at forhindre en enkelt anvenders brug af DAWA påvirker andre anvendere. F.eks. i form af lange svartider eller fejl i kald af servicen.

Hvis grænsen på 10 samtidige requests overskrides returneres responses med HTTP statuskoden 429 Too Many Requests.

Kodeeksempler

At se på kodeeksempler er en god måde at finde ud af hvordan DAWA anvendes. Du kan finde en række kodeeksempler på https://github.com/DanmarksAdresser:

Vi planlægger at tilføje kodeeksempler i andre sprog og platforme. Hvis du vil bidrage med et kodeeksempel i dit favorit programmeringssprog, er du meget velkommen.