# Historik og tidsrejser

BBR, Matriklen og adresseregistret er bitemporale. Med `?asOf=` får du posten, som den var registreret på en dato, og med `/historik` får du hele rækken af versioner.

## To måder at se bagud

| Endpoint | Hvad du får |
| --- | --- |
| `GET /v1/bbr/ejendom/:bfe?asOf=` | Ejendommen og dens bygninger, som de var registreret på datoen. |
| `GET /v1/matrikel/ejendom/:bfe?asOf=` | Jordstykkerne, som de var registreret på datoen. |
| `GET /v1/adresse/:uuid?asOf=` | Adressen, som den var registreret på datoen. |
| `GET /v1/bbr/ejendom/:bfe/historik` | Versionerne af hver af ejendommens nuværende bygninger, nyeste først. |
| `GET /v1/matrikel/ejendom/:bfe/historik` | Versionerne af hvert jordstykke, nyeste først. |
| `GET /v1/adresse/:uuid/historik` | Versionerne af adressen eller husnummeret, nyeste først. |

Brug `asOf`, når du kender datoen — fx en handels- eller vurderingsdato. Brug `/historik`, når du vil se forløbet eller finde tidspunktet for en ændring. Se referencen for [BBR-historik](https://grundfast.dk/docs/api/bbr-historik) og [Matrikel-historik](https://grundfast.dk/docs/api/matrikel-historik).

> **Kræver Scale** Både `asOf` og `/historik` kræver Scale-planen eller højere. På en lavere plan svarer API’et `402`, og kaldet tæller ikke. Uden `asOf` er de tre opslag åbne på alle planer. Se [/priser](https://grundfast.dk/priser).

## Et opslag på en dato

`asOf` er en ISO 8601-dato (`2019-01-01`, læst som midnat UTC) eller et fuldt tidspunkt. Datoen skal ligge fra 1990-01-01 og må ikke ligge i fremtiden; ellers svarer API’et `400`. Svaret har samme form som det aktuelle opslag, og tidspunktet gentages i `meta.as_of`.

**cURL**

```bash
curl "https://api.grundfast.dk/v1/bbr/ejendom/5651067?asOf=2019-01-01" \
  -H "Authorization: Bearer gf_live_..."
```

**TypeScript-SDK**

```ts
import { GrundfastClient } from '@grundfast/sdk';

const gf = new GrundfastClient({ apiKey: 'gf_live_...' });

const ejendom = await gf.ejendom(5651067, '2019-01-01');
console.log(ejendom.meta.as_of); // "2019-01-01T00:00:00.000Z"

const matrikel = await gf.matrikel(5651067, new Date('2019-01-01'));
const adresse = await gf.adresse('0a3f509b-eeab-32b8-e044-0003ba298018', '2019-01-01');
```

**Python**

```py
import requests

res = requests.get(
    "https://api.grundfast.dk/v1/bbr/ejendom/5651067",
    params={"asOf": "2019-01-01"},
    headers={"Authorization": "Bearer gf_live_..."},
    timeout=30,
)
res.raise_for_status()
for bygning in res.json()["bygninger"]:
    print(bygning["opfoerelsesaar"], bygning["areal"]["samlet_boligareal_m2"])
```

- Et `asOf`-opslag går direkte til kilden og bruger ikke vores cache. Det er derfor langsommere end et aktuelt opslag, og under et udfald hos kilden svarer det med en fejl i stedet for en cachet kopi.
- Et BBR-opslag med `asOf` bærer ikke dagens vurdering: feltet `vurdering` udelades.
- Fandtes ejendommen ikke på datoen, svarer API’et `404`.
- Matriklens registreringshistorik begynder med Matriklen2-indlæsningen 3. juni 2018. Et `asOf` før den dato svarer derfor `404` for alle ejendomme, også dem der fandtes længe før; `/historik` viser hvert jordstykkes tidsvinduer.
- Matriklens historiske opslag kræver en kilde, der ikke er sat op i alle miljøer; mangler den, svarer endpointet `503`. Geometrien på datoen hentes, når kilden har den; ellers er den `null`, mens attributterne stadig returneres.
- Kun de tre opslag ovenfor tager `asOf`. Øvrige endpoints, fx `/geojson` og `:batch`, svarer altid med den aktuelle version.

## Hele tidslinjen

```ts
const bbr = await gf.ejendomHistorik(5651067);         // BbrHistorikResponse
for (const bygning of bbr.bygninger) {
  for (const v of bygning.versioner) {
    console.log(v.virkning_fra, v.virkning_til, v.areal.samlet_boligareal_m2);
  }
}

const matrikel = await gf.matrikelHistorik(5651067);   // MatrikelHistorikResponse
const adresse = await gf.adresseHistorik('0a3f509b-eeab-32b8-e044-0003ba298018'); // AdresseHistorikResponse
```

Hver version bærer fire tidsstempler. `virkning_fra`/`virkning_til` er, hvornår forholdet gjaldt i virkeligheden; `registrering_fra`/`registrering_til` er, hvornår registret kendte til det. `*_til` er `null` på den gældende version.

| Svar | Indhold pr. version |
| --- | --- |
| BBR (`type: "bbr_historik"`) | `bygninger[].versioner[]` med anvendelse, opførelsesår, om-/tilbygningsår, etager, areal, materialer og varme. |
| Matriklen (`type: "matrikel_historik"`) | `jordstykker[].versioner[]` med matrikelnummer, ejerlav, areal og kommunekode. |
| Adresse (`type: "adresse_historik"`) | `versioner[]` med status, husnummer eller etage og dør. `niveau` siger, om tidslinjen er for en adresse eller et husnummer. |

- BBR-historikken dækker de bygninger, der står på ejendommen i dag (`meta.omfang: "aktuelle_bygninger"`). En nedrevet bygnings tidslinje er ikke med.
- `afkortet: true` betyder, at de ældste versioner eller nogle bygninger/jordstykker er udeladt, fordi ejendommen er meget stor.
- Historikken rækker så langt tilbage, som registret selv fører den. Vi opdigter ikke versioner.

## Hvilke registre har historik

BBR, Matriklen og DAR (adresser). DAGI, DHM, stednavne og de øvrige punktregistre returnerer den gældende tilstand. Ejendomsvurderingen er i sig selv en tidsserie: `/v1/vurdering/:bfe` returnerer alle vurderingsår (se [Ejendomsvurdering](https://grundfast.dk/ejendomsvurdering-api)).