Svar, null og friskhed

Alle svar er JSON i UTF-8 og følger de samme konventioner på tværs af registrene. Kender du dem, kan du læse ethvert endpoint.

Konventioner

JSON i UTF-8. Danske tegn (æ, ø, å) leveres som de er.
Feltnavne på dansk uden specialtegn, i snake_case: opfoerelsesaar, samlet_boligareal_m2, inden_for.
Enheder står i feltnavnet: _m2, _m, _kr. Beløb i ejendomsvurderingen er hele kroner.
meta på registersvar fortæller, hvor data kommer fra (kilde), og for de fleste også grundfast_version.

Kodefelter

Et felt, der i kilden er en kode, leveres som et objekt med både koden og den danske tekst. Gem koden, hvis du vil sammenligne eller filtrere; vis teksten.

json

"anvendelse": { "kode": "120", "tekst": "Fritliggende enfamiliehus" },
"materialer": {
  "ydervaeg": { "kode": "1", "tekst": "Mursten" },
  "ydervaeg_supplerende": null,
  "tag": { "kode": "5", "tekst": "Tegl" },
  "tag_supplerende": null
}

Et kodefelt er null, når registret ikke har en værdi. Kodelisterne for BBR kan hentes uden nøgle; se BBR.

null betyder ukendt

null betyder altid, at vi ikke ved det — at registret ikke har en værdi, eller at opslaget ikke kunne gennemføres. Det bliver aldrig til 0, false eller en tom streng, for det ville være en påstand om virkeligheden, som ingen har målt.

Felt	`null` betyder	Ikke det samme som
`bygninger[].fredning`	Vi kunne ikke slå bygningen op i fredningsregistret.	`fredet: false` — at bygningen er undersøgt og ikke fredet.
`terraen_m` (DHM)	Højdemodellen har ingen data i punktet.	`0` — en helt realistisk kote ved kysten. Kan kilden ikke nås, svarer API’et `502`.
`linjer.*.inden_for` (byggelinjer)	Netop den linjes kilde svarede ikke (`status: "utilgaengelig"`).	`false` — at punktet ligger uden for linjen.
`hoejde_m` (bygningshøjder)	Højden kunne ikke måles; `aarsag` siger hvorfor.	`0` eller en højde beregnet ud fra etageantal.
`afvigende_etager` (BBR)	Registret har ingen værdi.	Koden `0` — "ingen afvigende etager".

Svar på ja/nej-spørgsmål, som fx om et punkt er områdeklassificeret, er aldrig false på grund af en fejl hos kilden. Kan kilden ikke svare, får du en fejl, så et "nej" altid er målt.

Koordinater

Geometri leveres i WGS84 som [lon, lat] — GeoJSON-rækkefølge, længdegrad først — med de oprindelige EPSG:25832-koordinater ved siden af. Se Koordinatsystemer og geometri.

json

"geometri": {
  "type": "Point",
  "coordinates": [9.532961, 56.1578452],
  "epsg25832": [533103.83, 6223775.44]
}

Svar-headere

Header	Betydning
X-Request-Id	Id for kaldet. Angiv det, hvis du kontakter support.
X-Took-Ms	Vores behandlingstid for kaldet i hele millisekunder — på alle svar, også fejl. Forskellen til din egen svartid er netværket og alt imellem. Kan læses fra browseren (CORS).
X-Grundfast-Environment	`live` eller `test` efter nøglens type.
X-Grundfast-Stale	`true`, når svaret er vores cachede kopi, fordi kilden ikke svarede. Mangler, når svaret er frisk.
X-Grundfast-Cache-Age	Den cachede kopis alder i sekunder. Sættes kun sammen med `X-Grundfast-Stale`.
X-RateLimit-, X-Quota-	Burst-grænse og månedskvote. Se Rate limits.
Retry-After	På `429` (og visse `503`): sekunder før du bør prøve igen.
Server-Timing	På et BBR-opslag, der ikke kom fra cachen: hvor lang tid de enkelte trin tog. Nyttigt, når du vil forstå et langsomt kald.
Cache-Control	`private` — svaret er til dig og må ikke gemmes i en delt cache.

Friskhed og cachet kopi

Registrenes kilder har perioder med udfald. Vi gemmer det seneste gode svar, og hvis kilden ikke svarer, får du den cachede kopi i stedet for en fejl. Svaret er da markeret:

http

X-Grundfast-Stale: true
X-Grundfast-Cache-Age: 5400

Afgør selv, om alderen er acceptabel for dit brug. Er der sat et loft over, hvor gammel en kopi må være, svarer API’et 502 eller 503 i stedet for at levere en ældre kopi. TypeScript-SDK’et giver dig signalet som stale og cacheAge via *WithMeta()-metoderne. Den aktuelle status for kilderne står på /status.

Kalder du API’et direkte fra en browser på et andet domæne, skal domænet være godkendt til CORS, og de ovenstående headere kan da læses. Hold alligevel nøglen på serveren; se Godkendelse.