Batch og eksport

Batch-endpoints

• Højst 50 id’er pr. kald. Dubletter slås sammen.
• 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.
• 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.

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

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

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

// Op til 50 i ét kald — 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 vilkårligt 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 findes en eksport, der kører i baggrunden og leverer én fil. Den kræver Scale-planen.

1. 1

   Opret jobbet

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

   bashKopiér

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

   Hent filen

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

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');