Formater: JSON, CSV, GeoJSON, NDJSON og struktur

Standardsvaret er JSON i DAWA's nestede form. På adresselisterne kan du bede om CSV, GeoJSON eller NDJSON med format=, og om en flad eller kort JSON-form med struktur=. Parametrene fungerer som i DAWA. Her er, hvad hvert endpoint understøtter.

Hvad hvert endpoint understøtter#

To ting at være opmærksom på:

• En ukendt værdi i format eller struktur på /adresser og /adgangsadresser giver 400 invalid_query_parameter.
• På endpoints uden format bliver parameteren ignoreret uden fejl. /postnumre?format=csv giver JSON.

struktur: nestet, flad eller mini#

nestet er standarden: adressen med indlejrede objekter for adgangsadresse, vejstykke, postnummer, kommune, sogn osv. Koordinaterne ligger i adgangsadresse.adgangspunkt.koordinater.

flad samler alt i ét niveau med DAWA's flade feltnavne som kommunekode, sognenavn og kvhx. Koordinaterne står i begge systemer på én gang: wgs84koordinat_længde, wgs84koordinat_bredde, etrs89koordinat_øst og etrs89koordinat_nord.

mini er et lille fladt objekt til lister og dropdowns med DAWA's nøgler: id, status, darstatus, vejkode, vejnavn, adresseringsvejnavn, husnr, etage, dør, supplerendebynavn, postnr, postnrnavn, stormodtagerpostnr, stormodtagerpostnrnavn, kommunekode, x, y, href, betegnelse og adgangsadresseid.

import os
import requests

r = requests.get(
    "https://api.danadresse.dk/adresser",
    params={"postnr": "4200", "vejnavn": "Rådhuspladsen", "husnr": "1",
            "struktur": "mini", "per_side": 1},
    headers={"X-Api-Key": os.environ["DANADRESSE_API_KEY"]},
    timeout=10,
)
r.raise_for_status()
adresse = r.json()[0]
print(sorted(adresse))
print(adresse["betegnelse"], adresse["x"], adresse["y"])

Til at gemme i en database er flad ofte nemmest, fordi hver nøgle bliver en kolonne. Til at vise et forslag er mini nok.

CSV#

format=csv giver en kommasepareret fil med en overskriftslinje. Kolonnerne er faste og uafhængige af struktur:

curl -s "https://api.danadresse.dk/adresser?postnr=4200&vejnavn=R%C3%A5dhuspladsen&husnr=1&per_side=3&format=csv" \
  -H "X-Api-Key: $DANADRESSE_API_KEY"

id,status,vejnavn,husnr,etage,dør,supplerendebynavn,postnr,postnrnavn,kommunekode,kommunenavn,vejkode,etrs89koordinat_øst,etrs89koordinat_nord,wgs84koordinat_bredde,wgs84koordinat_længde,betegnelse
0a3f50ae-b4ee-32b8-e044-0003ba298018,1,Rådhuspladsen,1,st,th,,4200,Slagelse,0330,Slagelse,1407,649189.55,6142347.15,55.40464424,11.35623868,"Rådhuspladsen 1, st. th, 4200 Slagelse"

/adgangsadresser har de samme kolonner uden etage og dør og med adresseringsvejnavn. Det er færre kolonner end DAWA's CSV, som også havde fx matrikeldata. Skal du bruge flere felter, så hent JSON med struktur=flad og skriv din egen CSV.

• Filen er UTF-8 uden BOM. Åbner du den med dobbeltklik i Excel på Windows, bliver æøå forkerte. Se Æ, ø og å.
• Filen har altid begge koordinatsystemer: etrs89koordinat_øst og etrs89koordinat_nord i meter og wgs84koordinat_bredde og wgs84koordinat_længde i grader. Det gælder uanset srid.
• CSV følger side og per_side som alt andet. Se Paginering.

GeoJSON#

format=geojson giver en FeatureCollection, som du kan lægge direkte i Leaflet, Mapbox, QGIS eller geojson.io. Hver adresse er en Feature med et Point og de flade felter som properties:

import os
import requests

r = requests.get(
    "https://api.danadresse.dk/adgangsadresser",
    params={"postnr": "8000", "per_side": 5, "format": "geojson"},
    headers={"X-Api-Key": os.environ["DANADRESSE_API_KEY"]},
    timeout=10,
)
r.raise_for_status()
fc = r.json()
print(fc["type"], "med", len(fc["features"]), "punkter")
first = fc["features"][0]
print(first["geometry"]["coordinates"], first["properties"]["adressebetegnelse"])

{
  "type": "FeatureCollection",
  "crs": {"type": "name", "properties": {"name": "EPSG:4326"}},
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [10.20285443, 56.14811374]},
      "properties": {
        "id": "…",
        "kvh": "…",
        "husnr": "90A",
        "x": 10.20285443,
        "y": 56.14811374,
        "adressebetegnelse": "Jægergårdsgade 90A, 8000 Aarhus C"
      }
    }
  ]
}

Svaret er forkortet. Feltet crs fortæller koordinatsystemet: EPSG:4326 (standarden, længdegrad først) eller EPSG:25832, når du sender srid=25832. GeoJSON-standarden (RFC 7946) bruger WGS84, og mange værktøjer ignorerer crs, så brug srid=4326, medmindre dit værktøj læser UTM.

format=geojsonz giver det samme med højden som tredje koordinat, når den er kendt.

NDJSON#

format=ndjson giver én JSON-adresse pr. linje (application/x-ndjson). Det er nemt at skrive til en fil eller sende videre til et værktøj, der læser linje for linje. struktur virker også her:

curl -s "https://api.danadresse.dk/adresser?postnr=8000&per_side=3&format=ndjson&struktur=mini" \
  -H "X-Api-Key: $DANADRESSE_API_KEY"

NDJSON på /adresser er stadig én side. Det fulde datasæt får du som NDJSON fra /replikering/udtraek. Se Paginering.

JSONP: virker, men brug helst fetch#

Som i DAWA pakker callback=navn svaret ind som navn(…); med Content-Type: application/javascript. Det virker på de DAWA-kompatible stier. Et <script>-tag kan ikke sende headere, så med JSONP skal nøglen stå som api_key i URL'en.

API'et sender Access-Control-Allow-Origin: *, så du kan også kalde det direkte med fetch fra enhver side. Det er bedre, fordi du så kan se statuskoden og læse fejlsvaret. Gammel kode med jQuery og JSONP:

$.ajax({
  url: "https://dawa.aws.dk/autocomplete",
  dataType: "jsonp",
  data: { q: tekst },
  success: visForslag,
});

Den virker mod api.danadresse.dk, når du skifter domænet og tilføjer api_key i data. Samme kald med fetch. Brug en browsernøgle, der er låst til dit domæne, se Browsernøgler og tilladte domæner:

const API_KEY = "dawa_live_din_browsernøgle"; // låst til dit domæne

async function hentForslag(tekst) {
  const url = new URL("https://api.danadresse.dk/autocomplete");
  url.searchParams.set("q", tekst);
  const res = await fetch(url, { headers: { "X-Api-Key": API_KEY } });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

hentForslag("Rådhuspladsen 1").then(visForslag);

Med jQuery kan du nøjes med at skifte dataType: "jsonp" til dataType: "json" og tilføje nøglen i headers. Får du en CORS-fejl, så se CORS-fejl.

Næste skridt#

• Koordinater og srid 4326/25832
• Æ, ø og å: tegnsæt og URL-kodning
• Paginering med side og per_side