Adresse eller adgangsadresse? Datamodellen

Danske adresser findes i to niveauer: adgangsadressen er døren ud til vejen, og adressen er den enkelte bolig eller enhed bag døren. Begge har deres eget id og deres eget endpoint. Blander du dem sammen, får du 404 eller tomme lister, så det er værd at have styr på forskellen fra starten.

De to begreber#

En opgang i en etageejendom er én adgangsadresse med mange adresser, én pr. lejlighed. En villa er typisk én adgangsadresse med én adresse, hvor etage og dør er null. Data om bygningen (BBR, matrikel, kommune, sogn, koordinat) hører til adgangsadressen. Data om den enkelte bolig (fx BBR-enheden) hører til adressen.

Id'erne#

Begge id'er er UUID'er, og de er forskellige. Et adresse-svar indeholder adgangsadressen som indlejret objekt, så du får begge id'er i ét kald:

{
  "id": "0a3f50ae-b4ee-32b8-e044-0003ba298018",
  "kvhx": "03301407___1_st__th",
  "etage": "st",
  "dør": "th",
  "adressebetegnelse": "Rådhuspladsen 1, st. th, 4200 Slagelse",
  "adgangsadresse": {
    "id": "0a3f5084-62c3-32b8-e044-0003ba298018",
    "kvh": "03301407___1",
    "husnr": "1",
    "adressebetegnelse": "Rådhuspladsen 1, 4200 Slagelse",
    "adgangspunkt": {"koordinater": [11.35623868, 55.40464424]}
  }
}

Svaret er forkortet. I struktur=flad, struktur=mini og i autocomplete-forslagenes data hedder adgangsadressens id adgangsadresseid.

Hent en adresse og alle de andre adresser bag samme dør:

import os
import requests

API = "https://api.danadresse.dk"
headers = {"X-Api-Key": os.environ["DANADRESSE_API_KEY"]}

r = requests.get(f"{API}/adresser/0a3f50ae-b4ee-32b8-e044-0003ba298018",
                 headers=headers, timeout=10)
r.raise_for_status()
adresse = r.json()
adgang = adresse["adgangsadresse"]
print("adresse-id:      ", adresse["id"], "kvhx", adresse["kvhx"])
print("adgangsadresse-id:", adgang["id"], "kvh ", adgang["kvh"])

r = requests.get(f"{API}/adresser",
                 params={"adgangsadresseid": adgang["id"], "struktur": "mini"},
                 headers=headers, timeout=10)
r.raise_for_status()
for enhed in r.json():
    print(" -", enhed["betegnelse"])

kvh og kvhx#

Før UUID'erne blev adresser identificeret med koder. Mange ældre systemer gemmer dem stadig, og API'et kan slå op på dem:

• kvh (12 tegn) = kommunekode (4) + vejkode (4) + husnummer (4, fyldt op med _ foran). 03301407___1 er kommune 0330, vej 1407, husnummer 1.
• kvhx (19 tegn) = kvh + etage (3, fyldt op med _ foran) + dør (4, fyldt op med _ foran). 03301407___1_st__th er stuen til højre.

curl -s "https://api.danadresse.dk/adgangsadresser?kvh=03301407___1" \
  -H "X-Api-Key: $DANADRESSE_API_KEY"

Til en bestemt enhed bruger du /adresser?kvhx=03301407___1_st__th. En kvh, der ikke er 12 tegn, giver 400 med koden invalid_kvh. En kvhx, der ikke er 19 tegn, giver invalid_kvhx.

Vejkoden er kun entydig inden for en kommune, og husnumre kan blive omnummereret. Brug kvh og kvhx til at matche gamle data, og gem UUID'en fremover.

Autocomplete og type#

/autocomplete arbejder i tre trin, mens brugeren skriver: først vejnavne, så husnumre (adgangsadresser), så etager og døre (adresser). Hvert forslag har et type-felt, og betydningen af data.id afhænger af det:

Med parameteren type låser du trinnet:

• type=adresse giver altid adresser (enheder), også når brugeren kun har skrevet vej og husnummer.
• type=adgangsadresse stopper ved husnummeret og spørger aldrig om etage og dør. adgangsadresserOnly=true gør det samme.
• type=vejnavn giver kun vejnavne.

Læs altid type på det valgte forslag, før du bruger data.id. Uden type i kaldet kan det samme felt give et adgangsadresse-id det ene øjeblik og et adresse-id det næste.

Det forkerte id på det forkerte endpoint#

Id'erne er ikke ombyttelige. Et adgangsadresse-id på /adresser/{id} giver:

{
  "type": "ResourceNotFoundError",
  "title": "Adresse 0a3f5084-62c3-32b8-e044-0003ba298018 not found",
  "details": null,
  "code": "not_found"
}

Den anden vej er API'et mere tilgivende: et adresse-id på /adgangsadresser/{id} svarer med den adgangsadresse, enheden hører til. Svarets id er så adgangsadressens id, ikke det id, du sendte.

På lister giver det forkerte id en tom liste: /adresser?id=<adgangsadresse-id> finder ingenting. Brug /adresser?adgangsadresseid=<id> til at finde enhederne bag en dør.

Berigelses-endpoints under /api/v1/enrich/adresser/{id}/… tager begge slags id. Et adresse-id bliver slået op på den adgangsadresse, det hører til, så fx dagi, bbr og climate giver det samme svar for alle lejligheder bag samme dør.

Hvilket id skal du gemme?#

Gem også adresseteksten (adressebetegnelse), som den så ud, da brugeren valgte den. Adresser kan blive omdøbt eller nedlagt, og så er det rart at vide, hvad der stod. Læs mere i Gem adressens id og status, darstatus og nedlagte adresser.

Næste skridt#

• Gem adressens id i stedet for teksten
• Koordinater og srid
• Fejl 400 og 404