# 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](https://grundfast.dk/docs/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](https://grundfast.dk/docs/koordinater).

```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](https://grundfast.dk/docs/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](https://grundfast.dk/docs/sdk) giver dig signalet som `stale` og `cacheAge` via `*WithMeta()`-metoderne. Den aktuelle status for kilderne står på [/status](https://grundfast.dk/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](https://grundfast.dk/docs/godkendelse#hold-noeglen-paa-serveren).