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 og 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.

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 "https://api.grundfast.dk/v1/bbr/ejendom/5651067?asOf=2019-01-01" \
  -H "Authorization: Bearer gf_live_..."

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 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

historik.tstypescript

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).