@grundfast/sdk

Official TypeScript SDK for the Grundfast API — the convenient old services.datafordeler.dk shape (translated kodelister, re-joined names, current-only data, WGS84 geometry, auto-pagination) over Denmark's new entity-based Datafordeler backend. Register #1 is BBR, #2 is Matriklen.

Full API reference: grundfast.dk/docs/sdk.

Installation

Launching on npm shortly. Until then, call the REST API directly (same data, no dependency) — see the docs. Once published:

npm install @grundfast/sdk
# or
bun add @grundfast/sdk

Ships dual ESM + CommonJS with bundled type declarations — works in Node, Bun, and the browser.

Quick Start

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

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

// Resolve one property by its BFE (Bestemt Fast Ejendom) number.
const ejendom = await gf.ejendom(5651067);
console.log(ejendom.jordstykke.ejerlav_navn, ejendom.bygninger.length);

The client defaults to https://api.grundfast.dk. Override baseUrl (or inject a custom fetch) via the constructor options:

const gf = new GrundfastClient({
	apiKey: 'gf_live_…',
	baseUrl: 'https://api.grundfast.dk',
	timeoutMs: 15000, // per-request abort timeout (default 15s; 0 disables)
});

Every request is aborted after timeoutMs so a hung upstream never hangs your await — a timeout throws GrundfastError with status: 408.

Try it without a key

The demo endpoints run offline from a bundled fixture — no API key required:

const gf = new GrundfastClient();
const demo = await gf.demoEjendom();
const fc = await gf.demoEjendomGeoJson(); // WFS-compatible GeoJSON FeatureCollection
const koder = await gf.kodeliste('varmeinstallation'); // translated code list

Keyed endpoints

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

// Clean, re-joined property rollup.
const ejendom = await gf.ejendom(5651067);

// Same property as a WFS-compatible GeoJSON FeatureCollection (one Feature per building).
const geojson = await gf.ejendomGeoJson(5651067);

// Matriklen (cadastre) rollup.
const matrikel = await gf.matrikel(5651067);

// Building(s) for a BFE — same rollup shape as ejendom() (resolved from the same join).
const bygning = await gf.bygning(5651067);

// Per-building GeoDanmark footprint polygons (the real outlines BBR can't give).
const footprints = await gf.geodanmarkBygninger(5651067);
console.log(footprints.buildings[0]?.rings, footprints.attribution); // CC BY 4.0 credit

Scope

This SDK is a typed data-access client for the read endpoints — every live register (BBR, Matriklen, DAGI, DHM, Stednavne, DAR/adresse, CVR), the DAWA-compatible drop-in layer (postnumre, vejnavne, ejerlav, autocomplete, datavask, reverse-geocoding), GeoDanmark building footprints, kodelister, point-in-time lookups (?asOf/historik), and the batch + bulk-export helpers. Account, API-key, and billing management are done in the dashboard (you mint keys there), so the SDK intentionally exposes no auth/keys/me/billing methods.

Batch & streaming

// Up to 50 BFEs per call. Partial-failure aware: each BFE lands in results or errors,
// and the call itself succeeds even if some BFEs fail. One billable unit per deduped BFE.
const { results, errors } = await gf.ejendomBatch([5651067, 12345678]);

// Auto-paginate an arbitrarily large BFE array: chunks into <=50-sized batch calls
// and yields each successfully-resolved property (failures are skipped — use
// ejendomBatch directly if you need to inspect them).
for await (const item of gf.ejendomStream(thousandsOfBfes)) {
	console.log(item.bfe, item.ejendom.antal_bygninger, item.stale);
}

Error handling

Every non-2xx response (and a request timeout, as status: 408) throws a GrundfastError carrying the HTTP status. On a 429 the retryAfter field holds the Retry-After seconds so you can back off intelligently:

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

try {
	await gf.ejendom(999999999);
} catch (err) {
	if (err instanceof GrundfastError) {
		console.error(err.status, err.message); // e.g. 404 "property not found"
		if (err.status === 429 && err.retryAfter) {
			await new Promise((r) => setTimeout(r, err.retryAfter * 1000));
		}
	}
}

Links

• Grundfast — Danish property & geodata API
• SDK reference
• API documentation