Spring til indhold

Grundfast

Batch og eksport

Slå op til 50 ejendomme, adresser, punkter eller områder op i ét kald (flere på Scale og Enterprise), eller lad en asynkron eksport hente op til 5.000 og levere dem som én fil. Længere lister går som et job.

På denne side· 4 afsnit

Batch-endpoints

EndpointBodyPlan
POST /v1/bbr/ejendom:batch{ "bfe": [5651067, …] }Pro
POST /v1/matrikel/ejendom:batch{ "bfe": [ … ] }Pro
POST /v1/adresse:batch{ "uuid": [ … ] }Pro
POST /v1/dagi:batch{ "tema": "kommune", "kode": ["0101", …] }Pro
POST /v1/datavask/adgangsadresser:batch{ "betegnelser": [ … ] }Pro
POST /v1/adgangsadresser/reverse:batch{ "punkter": [{ "lon", "lat", "id" }], "radius" }Pro
POST /v1/dagi/reverse:batch{ "punkter": [{ "lon", "lat", "id" }] }Pro
POST /v1/miljoe/screening:batch{ "bfe": [ … ] }Pro
POST /v1/dhm/kote:batch{ "punkter": [{ "lon", "lat", "id" }] }Alle planer
  • Antallet pr. kald følger planen: 50 på Pro, 100 på Scale og 150 på Enterprise. Dubletter slås sammen før optællingen. En længere liste afvises med 402, der nævner den plan, der tager den, og tæller ikke.
  • Tre batches står fast på 50 på alle planer, fordi hvert id er sit eget spørgsmål til en kilde uden cache: miljoe/screening:batch (otte opslag pr. BFE), dagi/reverse:batch (ét DAGI-opslag pr. punkt) og dhm/kote:batch.
  • Har du tusinder af rækker, så send dem som et job i stedet for at dele dem op i batch-kald selv.
  • Kaldet tæller ét kald pr. unikt id mod kvoten — en batch er ikke billigere end enkeltopslag, men hurtigere og færre forespørgsler. Kun de id’er, der kunne slås op, faktureres som forbrug. Afvises hele kaldet med 4xx (fx et punkt uden for Danmark), tæller det som ét kald.
  • Batch kræver Pro-planen; på en lavere plan svarer API’et 402, og kaldet tæller ikke. dhm/kote:batch er undtaget og virker på alle planer, fordi den prissættes præcis som de enkelte koter.

Delvise fejl

Et batch-kald svarer 200, også når nogle id’er fejler. Hvert id lander enten i results eller i errors med sin egen status, så ét ukendt BFE ikke vælter resten. Kun en ugyldig body giver 400 for hele kaldet.

POST /v1/bbr/ejendom:batch
{
  "results": [
    { "bfe": 5651067, "ejendom": { "type": "ejendom", … }, "stale": false }
  ],
  "errors": [
    { "bfe": 999999999, "error": "property not found", "status": 404 }
  ],
  "requested": 2,
  "succeeded": 1,
  "failed": 1
}
  • Matriklen, adresse og DAGI har samme form; nøglen i hvert element er bfe, uuid eller kode, og DAGI-svaret gentager tema.
  • Datavask har ingen errors: hver adressestreng får et svar i results i samme rækkefølge, og en streng uden match får kategori: "C" og antal: 0.
  • dhm/kote:batch svarer med punkter og fejl samt forespurgt, besvaret og fejlet. Et punkt, der ikke kunne besvares, står i fejl — aldrig som en kote på null blandt de andre. Giv punkterne et id, så du kan parre svarene med dine hjørner.
  • stale: true på et element betyder, at netop det blev leveret fra vores cachede kopi. Se Svar, null og friskhed.

Med SDK’et

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

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

// Op til din plans loft i ét kald (50 på Pro) — delvise fejl i errors:
const { results, errors } = await gf.ejendomBatch([5651067, 999999999]);
for (const e of errors) console.warn(e.bfe, e.status, e.error);

// En lang liste: SDK'et deler den i kald á 50 og giver ejendommene én ad gangen.
// BFE'er, der fejler, springes over — brug ejendomBatch, hvis du skal se dem.
const mineBfeer: number[] = [5651067 /* … */];
for await (const { bfe, ejendom } of gf.ejendomStream(mineBfeer)) {
  console.log(bfe, ejendom.antal_bygninger);
}

const matrikler = await gf.matrikelBatch([5651067]);
const adresser = await gf.adresseBatch(['0a3f509b-eeab-32b8-e044-0003ba298018']);
const kommuner = await gf.dagiBatch('kommune', [101, 851]);
const vasket = await gf.datavaskBatch(['raadhuspladsen 1 saeby', 'Vejlebyvej 17 Vodskov']);
const koter = await gf.dhmKoter([
  { lon: 10.2036, lat: 56.1577, id: 'hjørne-a' },
  { lon: 10.2038, lat: 56.1578, id: 'hjørne-b' },
]);

SDK’et prøver batch-kald igen ved midlertidige fejl, fordi de er sikre at gentage: et kald, der endte i en serverfejl, er lagt tilbage i kvoten.

Asynkron eksport

Til større lister af kendte id’er findes en eksport, der kører i baggrunden og leverer det fulde objekt pr. id i én fil. Den kræver Scale-planen. Har du adresser i fritekst, punkter eller en liste over 5.000, er et job det rette værktøj.

EgenskabVærdi
Registrebbr og matrikel (liste af bfe), adresse (liste af uuid)
Formatercsv, ndjson, geojson
StørrelseHøjst 5.000 id’er pr. job
ForbrugÉt kald pr. unikt id, trukket ved oprettelsen. Id’er, der ikke kunne hentes, krediteres tilbage.
OpbevaringFilen gemmes i en periode efter jobbet er færdigt; resultAvailable siger, om den stadig kan hentes.
  1. Opret jobbet

    POST /v1/export med register, format og id’er. Svaret er 201 med { "job": { "id", "status": "queued", … } }.

    bash
    curl https://api.grundfast.dk/v1/export \
      -H "Authorization: Bearer gf_live_..." \
      -H "Content-Type: application/json" \
      -d '{ "register": "bbr", "format": "csv", "bfe": [5651067] }'
  2. Vent på at det bliver færdigt

    Hent GET /v1/export/:id, indtil status er completed (eller failed). requested, succeeded og failed viser, hvor mange id’er der blev hentet.

  3. Hent filen

    GET /v1/export/:id/download returnerer filen. Er jobbet ikke færdigt endnu, svarer den 409.

eksport.ts
const job = await gf.createExport({ register: 'bbr', format: 'csv', bfe: mineBfeer });

let status = job;
while (status.status === 'queued' || status.status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  status = await gf.getExport(job.id);
}
if (status.status === 'failed') throw new Error(status.error ?? 'eksporten fejlede');

const csv = await gf.downloadExport(job.id); // string
console.log(status.succeeded, 'af', status.requested, 'ejendomme');
En eksport er afgrænset af den liste id’er, du sender — det er ikke et udtræk af hele registret. createExport() prøves aldrig igen automatisk, så en netværksfejl ikke opretter et ekstra job. Se også GET /v1/export, som lister dine seneste jobs.