Introduktion

Log ind med Token

Der benyttes samme brugeradministration på Dataforsyningen, som du kender fra Kortforsyningen. Du kan derfor benytte samme brugernavn og adgangskode, som har givet adgang til kortforsyningen.dk og download.kortforsyningen.dk

Authentication - Login med Token

Benyttes i webapplikationer og GIS systemer, når du kalder API’er og webservices. Dataforsyningen er stateless, derfor skal token altid sendes med hver forespørgsel til Dataforsyningen, undtagen alle DAWA og Inspire OGC-tjenesterne.

Du skal være oprettet som bruger på Dataforsyningen og være logget ind, for at oprette og administrere dine tokens på Dataforsyningen.:

1. Klik på brugerikonet øverst i højre hjørne
2. Gå til "Administrer token til webservices og API’er"
3. Klik på ”Opret ny token”

Der bliver generet en token bestående af tilfældige tal og har et navn af tilfældige bogstaver og tal. Du kan ændre navnet på dine tokens, det anbefales hvis du bruger dine tokens til fx et fagsystem eller en specifik webløsning. Du kan også definere udløbsdata for tokens.

Token benyttes til at identificere sig overfor Dataforsyningen uden risiko for at afsløre brugernavn og adgangskode. Det kan f.eks. være relevant, hvis Dataforsyningens webservices er implementeret i webapplikationer tilgængelige for alle på internettet.

Token skal angives på én af følgende måder i requesten:

1. Som header parameteren token (anbefaler vi at bruge, da det er den mest sikre måde) ``` https://api.dataforsyningen.dk/{servicenavnet på tjenesten}

   token: {DinToken} ```

2. Som queryparameter token i URL'en https://api.dataforsyningen.dk/{servicenavnet på tjenesten}?token={DinToken}

En gyldig URL vil f.eks. se således ud:

https://api.dataforsyningen.dk/natur_friluftskort?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=TRUE&LAYERS=nfkort&STYLES=&WIDTH=256&HEIGHT=256&SRS=EPSG%3A25832&BBOX=559140.625%2C6199218.75%2C560000%2C6200078.125&token=xxx

Alle kald til Dataforsyningens API'erne og webservices skal bruge HTTPS, da der ikke understøttes HTTP, og token skal være angivet (undtagen alle DAWA og Inspire OGC-tjenesterne). Kald uden token angivet eller med ugyldig token vil fejle.

Bearer token

Token er den mest benyttet authentikations metode på Dataforsyningen. I nogle kald er det dog nødvendigt at bruge en bearer token i stedet. Denne virker som token men bliver autogenereret af Dataforsyingen og er kun gyldig i 24 timer. I fremtiden forventes det dog at det bliver muligt at benytte token for disse API'er.

Arkivmeta v2.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

APIet Arkivmeta giver adgang til at søge i metadata for en større samling historiske kort, dokumenter og benytte resultatet til at fremvise det skannede materiale.

Til adgang benyttes Dataforsyningens brugeradgang som ved andre tjenester.

Stier til kortfiler følger IIIF specifikationen og kan vises med en viser, der understøtter dette.

Base URLs:

• https://api.dataforsyningen.dk/rest/arkivmeta/v2.0

Authentication

• API Key (HeaderToken)

  • Parameter Name: token, in: header.

• API Key (QueryToken)

  • Parameter Name: token, in: query.

KortApi

Kort metadata API

getKort

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/kort HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /kort

Liste af kort der matcher søgekriterierne

Hvis gaeldendefra og gaeldendetil bliver brugt samtidig, er det alle kort, der er indenfor gyldighedsperioden eller har været gældende fra eller gældende til, i perioden

Parameters

Example responses

200 Response

{
  "total": 0,
  "kort": [
    {
      "id": "string",
      "alternativtitel": "string",
      "arketype": "string",
      "bemaerkning": "string",
      "daekningsomraade": [
        "string"
      ],
      "filer": [
        "string"
      ],
      "gaeldendefra": 0,
      "gaeldendetil": 0,
      "geometri": "string",
      "kortbladnummer": "string",
      "kortvaerk": "string",
      "maalestok": "string",
      "originalkortprojektion": "string",
      "originalehjoernekoordinater": "string",
      "registreringfra": "2019-08-24T14:15:22Z",
      "registreringtil": "2019-08-24T14:15:22Z",
      "titel": "string",
      "uniktkortnavn": "string"
    }
  ]
}

Responses

postKort

Code samples

POST https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/kort HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

POST /kort

Liste af kort der matcher søgekriterierne

Hvis gaeldendefra og gaeldendetil bliver brugt samtidig, er det alle kort, der er indenfor gyldighedsperioden eller har været gældende fra eller gældende til, i perioden

Parameters

Example responses

200 Response

{
  "total": 0,
  "kort": [
    {
      "id": "string",
      "alternativtitel": "string",
      "arketype": "string",
      "bemaerkning": "string",
      "daekningsomraade": [
        "string"
      ],
      "filer": [
        "string"
      ],
      "gaeldendefra": 0,
      "gaeldendetil": 0,
      "geometri": "string",
      "kortbladnummer": "string",
      "kortvaerk": "string",
      "maalestok": "string",
      "originalkortprojektion": "string",
      "originalehjoernekoordinater": "string",
      "registreringfra": "2019-08-24T14:15:22Z",
      "registreringtil": "2019-08-24T14:15:22Z",
      "titel": "string",
      "uniktkortnavn": "string"
    }
  ]
}

Responses

maalestok

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/maalestok HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/maalestok

Hent målestoksforhold

Leverer en liste af målestoksforhold

Parameters

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

kortvaerk

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/kortvaerker HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/kortvaerker

Hent kortværker

Leverer en liste af kortværker

Parameters

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

daekningsomraade

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/daekningsomraader HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/daekningsomraader

Hent dækningsområder

Leverer en liste af dækningsområder

Parameters

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

arketyper

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/arketyper HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/arketyper

Hent arketyper

Leverer en liste af tilgængelige arketyper

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

arketyperWithKortvaerker

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/arketyper/kortvaerker HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/arketyper/kortvaerker

Hent arketyper med underliggende kortværker

Leverer en liste af tilgængelige arketyper, med de kortværker som hører til

Example responses

200 Response

[
  {
    "arketype": "string",
    "arkenavn": "string",
    "kortvaerker": [
      "string"
    ]
  }
]

Responses

Response Schema

Status Code 200

kortById

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/kort/{arketype}/{id} HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /kort/{arketype}/{id}

Vis kort ud fra unik id

Parameters

Example responses

200 Response

{
  "id": "string",
  "alternativtitel": "string",
  "arketype": "string",
  "bemaerkning": "string",
  "daekningsomraade": [
    "string"
  ],
  "filer": [
    "string"
  ],
  "gaeldendefra": 0,
  "gaeldendetil": 0,
  "geometri": "string",
  "kortbladnummer": "string",
  "kortvaerk": "string",
  "maalestok": "string",
  "originalkortprojektion": "string",
  "originalehjoernekoordinater": "string",
  "registreringfra": "2019-08-24T14:15:22Z",
  "registreringtil": "2019-08-24T14:15:22Z",
  "titel": "string",
  "uniktkortnavn": "string"
}

Responses

ProtokolApi

Protokol metadata API

getDokument

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/dokument HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /dokument

Liste af dokumenter der matcher søgekriterierne

Disse er parametrerne i DokumentParam

Parameters

Example responses

200 Response

{
  "total": 0,
  "dokumenter": [
    {
      "id": "string",
      "arketype": "string",
      "titel": "string",
      "alternativtitel": "string",
      "registreringfra": "2019-08-24T14:15:22Z",
      "registreringtil": "2019-08-24T14:15:22Z",
      "uniktdokumentnavn": "string",
      "stinavn": "string",
      "bemaerkning": "string",
      "geometri": "string",
      "omraade": "string",
      "filer": [
        "string"
      ],
      "datatype": "string",
      "filtype": "string",
      "dokumentsamling": "string",
      "herredsnavn": "string",
      "herredsnummer": 0,
      "protokoltype": "string",
      "sogneid": 0,
      "sognenavn": "string"
    }
  ]
}

Responses

postDokument

Code samples

POST https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/dokument HTTP/1.1
Host: api.dataforsyningen.dk
Content-Type: application/json
Accept: application/json

POST /dokument

Liste af dokumenter der matcher søgekriterierne

Disse er parametrerne i DokumentParam

Body parameter

{
  "dokumentsamling": [
    "string"
  ],
  "fritekstsoegning": "string",
  "geometri": "string",
  "herredsnavn": "string",
  "herredsnummer": 0,
  "sogneid": 0,
  "sognenavn": "string",
  "titel": "string",
  "direction": "asc",
  "sort": "string",
  "limit": 100,
  "offset": 0
}

Parameters

Example responses

200 Response

{
  "total": 0,
  "dokumenter": [
    {
      "id": "string",
      "arketype": "string",
      "titel": "string",
      "alternativtitel": "string",
      "registreringfra": "2019-08-24T14:15:22Z",
      "registreringtil": "2019-08-24T14:15:22Z",
      "uniktdokumentnavn": "string",
      "stinavn": "string",
      "bemaerkning": "string",
      "geometri": "string",
      "omraade": "string",
      "filer": [
        "string"
      ],
      "datatype": "string",
      "filtype": "string",
      "dokumentsamling": "string",
      "herredsnavn": "string",
      "herredsnummer": 0,
      "protokoltype": "string",
      "sogneid": 0,
      "sognenavn": "string"
    }
  ]
}

Responses

getSognenavn

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/sognenavn HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/sognenavn

Hent sognenavne

Leverer en liste af sognenavne

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

getHerredsnavn

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/herredsnavn HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/herredsnavn

Hent herredsnavne

Leverer en liste af herredsnavne

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

getDokumentSamling

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/metadata/dokumentsamling HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /metadata/dokumentsamling

Hent dokumentsamlinger

Leverer en liste af dokumentsamlinger

Example responses

200 Response

[
  "string"
]

Responses

Response Schema

dokumentById

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/dokument/{arketype}/{id} HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /dokument/{arketype}/{id}

Find dokument ud fra unik id

Parameters

Example responses

200 Response

{
  "id": "string",
  "arketype": "string",
  "titel": "string",
  "alternativtitel": "string",
  "registreringfra": "2019-08-24T14:15:22Z",
  "registreringtil": "2019-08-24T14:15:22Z",
  "uniktdokumentnavn": "string",
  "stinavn": "string",
  "bemaerkning": "string",
  "geometri": "string",
  "omraade": "string",
  "filer": [
    "string"
  ],
  "datatype": "string",
  "filtype": "string",
  "dokumentsamling": "string",
  "herredsnavn": "string",
  "herredsnummer": 0,
  "protokoltype": "string",
  "sogneid": 0,
  "sognenavn": "string"
}

Responses

Liveliness/Readiness

ping

Code samples

GET https://api.dataforsyningen.dk/rest/arkivmeta/v2.0/ping HTTP/1.1
Host: api.dataforsyningen.dk
Accept: application/json

GET /ping

ping

Liveliness/readiness probe.

Example responses

200 Response

"string"

Responses

Schemas

KortDto

{
  "id": "string",
  "alternativtitel": "string",
  "arketype": "string",
  "bemaerkning": "string",
  "daekningsomraade": [
    "string"
  ],
  "filer": [
    "string"
  ],
  "gaeldendefra": 0,
  "gaeldendetil": 0,
  "geometri": "string",
  "kortbladnummer": "string",
  "kortvaerk": "string",
  "maalestok": "string",
  "originalkortprojektion": "string",
  "originalehjoernekoordinater": "string",
  "registreringfra": "2019-08-24T14:15:22Z",
  "registreringtil": "2019-08-24T14:15:22Z",
  "titel": "string",
  "uniktkortnavn": "string"
}

Properties

KortResult

{
  "total": 0,
  "kort": [
    {
      "id": "string",
      "alternativtitel": "string",
      "arketype": "string",
      "bemaerkning": "string",
      "daekningsomraade": [
        "string"
      ],
      "filer": [
        "string"
      ],
      "gaeldendefra": 0,
      "gaeldendetil": 0,
      "geometri": "string",
      "kortbladnummer": "string",
      "kortvaerk": "string",
      "maalestok": "string",
      "originalkortprojektion": "string",
      "originalehjoernekoordinater": "string",
      "registreringfra": "2019-08-24T14:15:22Z",
      "registreringtil": "2019-08-24T14:15:22Z",
      "titel": "string",
      "uniktkortnavn": "string"
    }
  ]
}

Properties

DokumentDto

{
  "id": "string",
  "arketype": "string",
  "titel": "string",
  "alternativtitel": "string",
  "registreringfra": "2019-08-24T14:15:22Z",
  "registreringtil": "2019-08-24T14:15:22Z",
  "uniktdokumentnavn": "string",
  "stinavn": "string",
  "bemaerkning": "string",
  "geometri": "string",
  "omraade": "string",
  "filer": [
    "string"
  ],
  "datatype": "string",
  "filtype": "string",
  "dokumentsamling": "string",
  "herredsnavn": "string",
  "herredsnummer": 0,
  "protokoltype": "string",
  "sogneid": 0,
  "sognenavn": "string"
}

Properties

DokumentResult

{
  "total": 0,
  "dokumenter": [
    {
      "id": "string",
      "arketype": "string",
      "titel": "string",
      "alternativtitel": "string",
      "registreringfra": "2019-08-24T14:15:22Z",
      "registreringtil": "2019-08-24T14:15:22Z",
      "uniktdokumentnavn": "string",
      "stinavn": "string",
      "bemaerkning": "string",
      "geometri": "string",
      "omraade": "string",
      "filer": [
        "string"
      ],
      "datatype": "string",
      "filtype": "string",
      "dokumentsamling": "string",
      "herredsnavn": "string",
      "herredsnummer": 0,
      "protokoltype": "string",
      "sogneid": 0,
      "sognenavn": "string"
    }
  ]
}

Properties

DokumentParam

{
  "dokumentsamling": [
    "string"
  ],
  "fritekstsoegning": "string",
  "geometri": "string",
  "herredsnavn": "string",
  "herredsnummer": 0,
  "sogneid": 0,
  "sognenavn": "string",
  "titel": "string",
  "direction": "asc",
  "sort": "string",
  "limit": 100,
  "offset": 0
}

Properties

ArketypeDto

{
  "arketype": "string",
  "arkenavn": "string",
  "kortvaerker": [
    "string"
  ]
}

Properties

DAWA - Generelt om Web API'et

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

Bemærk, at DAWA udfases. Du kan følge med i udfasningsplanerne her: https://dataforsyningen.dk/data/4924

Baseadresse

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

Dataformater

Alle typer data kan returneres i følgende formater:

JSON, Default

https://api.dataforsyningen.dk/adresser?postnr=8830&vejnavn=Bakkevej

Unden ekstra parameter retuneres svaret som JSON.

JSONP

https://api.dataforsyningen.dk/adresser?postnr=8830&vejnavn=Bakkevej&callback=cbFun

Ved brug af parameteren callback=cbFun retuneres svaret som JSONP.

NDJSON

https://api.dataforsyningen.dk/adresser?postnr=8830&vejnavn=Bakkevej&ndjson

Ved brug af parameteren ndjson retuneres svaret som NPJSON.

CSV

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

Ved brug af parameteren format=csv retuneres svaret som comma-separated values.

GeoJSON

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

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

Derudover understøttes også GeoJSON for de entiteter hvor det giver mening ved at bruge parameteren format=geojson

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

Vejstykker og adgangsadresser supporterer endvidere GeoJSON med højdeangivelse (z-koordinatet). Hvis man ønsker dette anvendes 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.

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

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

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

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

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

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

Download i browser

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

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=filnavn.csv

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

Parametervalidering

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

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 en fejl hvis der anvendes ukendte parametre.

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 ["https://https://en.wikipedia.org/wiki/Stemming">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 fleste tilfælde være bedst at benytte "datavask API'et".

Eksempler

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

• Find de adresser som matcher Lilledal 1

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

• Find alle vejnavne, som starter med vibor

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

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

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 API" med tilhørende javacript klientbibliotek, som giver en bedre brugeroplevelse til adresseindtastning.

Eksempler

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

• Find de adresser som matcher Lilledal 1

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

• Find alle vejnavne, som matcher vibor

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

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

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.

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

Grøndal sogn request returnerer side 3 med en sidestørrelse på 24 adresser per side.

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"

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

Eksempel på returneret fejlbeskrivelse:

Formatering

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

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:

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.

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

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:

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.

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

Hvis man f.eks. ønsker alle adresser på Gammel Kongevej 177 der ikke har angivet en etage gøres det følgende måde:

DAWA - Danmarks Adressers Web API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Base URLs:

• https://api.dataforsyningen.dk

Default

get__adgangsadresser

Code samples

GET https://api.dataforsyningen.dk/adgangsadresser HTTP/1.1
Host: api.dataforsyningen.dk

GET /adgangsadresser

Søg efter adresser. Returnerer de adresser som opfylder kriteriet. Med mindre der er behov for felter som kun er med i den fulde adressestruktur anbefaler vi at, man tilføjer parameteren struktur=mini, da dette vil resultere i bedre performance.

Parameters

Detailed descriptions

q: Søgetekst. Der søges i vejnavn, husnr, supplerende bynavn, postnr og postnummerets navn. Alle ord i søgeteksten skal matche adgangsadressen. Wildcard * er tilladt i slutningen af hvert ord. Der skelnes ikke mellem store og små bogstaver. Der returneres højst 1000 resultater ved anvendelse af parameteren. Parameteren "fuzzy" kan tilføjes for at lave fuzzy søgning. Hvis behovet er at fremsøge en enkelt adresse ud fra en adressetekst, så vil det i de fleste tilfælde være bedre at benytte datavask API'et.

Responses

get__adgangsadresser_autocomplete

Code samples

GET https://api.dataforsyningen.dk/adgangsadresser/autocomplete HTTP/1.1
Host: api.dataforsyningen.dk

GET /adgangsadresser/autocomplete

Autocomplete af adgangsadresser. Der kan anvendes de samme parametre som ved søgning, men bemærk at q parameteren fortolkes anderledes. Læs mere under autocomplete. DAWA tilbyder en kombineret autocomplete, som giver en bedre brugeroplevelse end autocomplete direkte i adgangsadresser.

Parameters

Responses

get__adgangsadresser_reverse

Code samples

GET https://api.dataforsyningen.dk/adgangsadresser/reverse?x=0&y=0 HTTP/1.1
Host: api.dataforsyningen.dk

GET /adgangsadresser/reverse

Find den adresse, som ligger nærmest det angivne koordinat. Som koordinatsystem kan anvendes ETRS89/UTM32 med srid=25832 eller WGS84/geografisk med srid=4326. Default er WGS84.

Parameters

Responses

get__adgangsadresser_{id}

Code samples

GET https://api.dataforsyningen.dk/adgangsadresser/{id} HTTP/1.1
Host: api.dataforsyningen.dk

GET /adgangsadresser/{id}

Modtag adresse med id.

Parameters

Responses

get__adresser

Code samples

GET https://api.dataforsyningen.dk/adresser HTTP/1.1
Host: api.dataforsyningen.dk

GET /adresser

Søg efter adresser. Returnerer de adresser som opfylder kriteriet. Med mindre der er behov for felter som kun er med i den fulde adressestruktur anbefaler vi at, man tilføjer parameteren struktur=mini, da dette vil resultere i bedre performance.

Parameters

Detailed descriptions

q: Søgetekst. Der søges i vejnavn, husnr, etage, dør, supplerende bynavn, postnr og postnummerets navn. Alle ord i søgeteksten skal matche adressebetegnelsen. Wildcard * er tilladt i slutningen af hvert ord. Der skelnes ikke mellem store og små bogstaver. Der returneres højst 1000 resultater ved anvendelse af parameteren. Parameteren "fuzzy" kan tilføjes for at lave fuzzy søgning. Hvis behovet er at fremsøge en enkelt adresse ud fra en adressetekst, så vil det i de fleste tilfælde være bedre at benytte datavask API'et.

Responses

get__adresser_autocomplete

Code samples

GET https://api.dataforsyningen.dk/adresser/autocomplete HTTP/1.1
Host: api.dataforsyningen.dk

GET /adresser/autocomplete

Autocomplete af adresser. Der kan anvendes de samme parametre som ved søgning, men bemærk at q parameteren fortolkes anderledes. Læs mere under autocomplete. DAWA tilbyder en kombineret autocomplete, som giver en bedre brugeroplevelse end autocomplete direkte i adresser.

Parameters

Responses

get__adresser_{id}

Code samples

GET https://api.dataforsyningen.dk/adresser/{id} HTTP/1.1
Host: api.dataforsyningen.dk

GET /adresser/{id}

Modtag adresse med id.

Parameters

Responses

get__datavask_adgangsadresser

Code samples

GET https://api.dataforsyningen.dk/datavask/adgangsadresser?betegnelse=string HTTP/1.1
Host: api.dataforsyningen.dk

GET /datavask/adgangsadresser

Datavask af adgangsadresse. Servicen modtager en adressebetegnelse og svarer med 1 eller flere adgangsadresser, som bedst matcher svaret. Endvidere er der en angivelse af hvor godt de fundne adgangsadresser matcher adressebetegnelsen.

Parameters

Responses

get__datavask_adresser

Code samples

GET https://api.dataforsyningen.dk/datavask/adresser?betegnelse=string HTTP/1.1
Host: api.dataforsyningen.dk

GET /datavask/adresser

Datavask af adresse. Servicen modtager en adressebetegnelse og svarer med 1 eller flere adresser, som bedst matcher svaret. Endvidere er der en angivelse af hvor godt de fundne adresser matcher adressebetegnelsen.

Parameters

Responses

get__jordstykker

Code samples

GET https://api.dataforsyningen.dk/jordstykker HTTP/1.1
Host: api.dataforsyningen.dk

GET /jordstykker

Søg efter jordstykker. Returnerer de jordstykker som opfyler søgekriterierne.

VIGTIGT: Der er udviklet en ny datamodel for matriklen, som er udstillet på Datafordeleren. DAWAs API er baseret en ældre datamodel, hvor data er konverteret tilbage fra den nye datamodel.

Parameters

Responses

get__jordstykker_autocomplete

Code samples

GET https://api.dataforsyningen.dk/jordstykker/autocomplete HTTP/1.1
Host: api.dataforsyningen.dk

GET /jordstykker/autocomplete

Autocomplete af jordstykker.

Parameters

Responses

get__jordstykker_{ejerlavkode}_{matrikelnr}

Code samples

GET https://api.dataforsyningen.dk/jordstykker/{ejerlavkode}/{matrikelnr} HTTP/1.1
Host: api.dataforsyningen.dk

GET /jordstykker/{ejerlavkode}/{matrikelnr}

Modtag jordstykket med den angivne ejerlavkode og matrikelnr

Parameters

Responses

get__jordstykker_reverse

Code samples

GET https://api.dataforsyningen.dk/jordstykker/reverse?x=0&y=0 HTTP/1.1
Host: api.dataforsyningen.dk

GET /jordstykker/reverse

Modtage jordstykket for det punkt der angives med x- og y-parametrene

Parameters

Responses

get__historik_adgangsadresser

Code samples

GET https://api.dataforsyningen.dk/historik/adgangsadresser HTTP/1.1
Host: api.dataforsyningen.dk

GET /historik/adgangsadresser

ADVARSEL: Experimentelt API. Der vil ske ændringer i dette API uden varsel, som ikke er bagudkompatible. Hent historik for adgangsadresser. Det er kun historiske værdier for udvalgte felter, der er medtaget. Bemærk, at udgåede adgangsadresser (statuskode 2 og 4) også medtages i svaret. Historikken returneres som en array af JSON-objekter, hvor hvert objekt repræsenterer en adgangsadresses tilstand i den periode, der er angivet med virkningstart og virkningslut. Hvis tilstanden er den aktuelle tilstand har virkningslut værdien null.

Parameters

Responses

get__historik_adresser

Code samples

GET https://api.dataforsyningen.dk/historik/adresser HTTP/1.1
Host: api.dataforsyningen.dk

GET /historik/adresser

ADVARSEL: Experimentelt API. Der vil ske ændringer i dette API uden varsel, som ikke er bagudkompatible. Hent historik for adresser. Det er kun historiske værdier for udvalgte felter, der er medtaget. Bemærk, at udgåede adresser (statuskode 2 og 4) også medtages i svaret. Historikken returneres som en array af JSON-objekter, hvor hvert objekt repræsenterer en adresses tilstand i den periode, der er angivet med virkningstart og virkningslut. Hvis tilstanden er den aktuelle tilstand har virkningslut værdien null.

Parameters

Responses

get__postnumre

Code samples

GET https://api.dataforsyningen.dk/postnumre HTTP/1.1
Host: api.dataforsyningen.dk

GET /postnumre

Søg efter postnumre. Returnerer de postnumre som opfylder kriteriet. Bemærk, at DAGI ikke indeholder erhvervspostnumre (fx 1790 og 8245), og at disse derfor ikke kan fremsøges igennem DAWA.

Bemærk, at postnumrenes geografi som udgangspunkt også medtager havområder (https://vis.dataforsyningen.dk/postnumre), hvilket ikke er det der ønskes i de fleste tilfælde. Ønskes landafgrænsede postnumre tilføjes parameteren landpostnumre https://vis.dataforsyningen.dk/postnumre?landpostnumre).

Parameters

Responses

get__postnumre_autocomplete

Code samples

GET https://api.dataforsyningen.dk/postnumre/autocomplete HTTP/1.1
Host: api.dataforsyningen.dk

GET /postnumre/autocomplete

Autocomplete på postnumre. Der kan anvendes de samme parametre som ved søgning, men bemærk at q parameteren fortolkes anderledes. Læs mere under autocomplete.

Parameters

Responses

get__postnumre_reverse

Code samples

GET https://api.dataforsyningen.dk/postnumre/reverse?x=0&y=0 HTTP/1.1
Host: api.dataforsyningen.dk

GET /postnumre/reverse

Modtage postnummeret for det punkt der angives med x- og y-parametrene

Parameters

Responses

get__postnumre_{nr}

Code samples

GET https://api.dataforsyningen.dk/postnumre/{nr} HTTP/1.1
Host: api.dataforsyningen.dk

GET /postnumre/{nr}

Modtag postnummer med id.

Parameters