danskadresseapi-sdk

Officiel JavaScript/TypeScript SDK for DanskAdresseAPI.

SDK'et taler vores native /v1-flade. Migrerer du fra DAWA, skal du sandsynligvis slet ikke bruge det — se Migration fra DAWA nedenfor.

v2.1 — streaming-iteratorer, webhook-verify og React-hooks.

Installation

bun add danskadresseapi-sdk
# eller: npm install danskadresseapi-sdk

Quick start

import { Addr } from 'danskadresseapi-sdk';

const addr = new Addr({ apiKey: process.env.ADDR_KEY! });

// Autocomplete (flad array, DAWA-paritet)
const hits = await addr.autocomplete({ q: 'Nørrebrog' });

// Reverse geocoding
const near = await addr.reverse({ lat: 55.6883, lon: 12.5571 });

// Datavask — rens én ustruktureret adressetekst
const check = await addr.datavask({
  betegnelse: 'Nørrebrogade 1, 2200 København N',
});
// → { kategori: 'A' | 'B' | 'C', resultater: [...] }

// Validering af en adresse du allerede har struktureret
const valid = await addr.validate({ vejnavn: 'Nørrebrogade', husnr: '1', postnr: '2200' });

Ressourcer

/v1-ressourcerne er eksponeret som namespace-objekter:

// Adresser & adgangsadresser
await addr.adresser.search({ q: 'storegade', postnr: '2100' });
await addr.adresser.byId('0a3f50a0-...');

// BBR
await addr.bbr.bygninger.byId('1234');
await addr.bbr.enheder.batch(['id1', 'id2', 'id3']);  // Pro+

// DAGI — kommunen for et punkt, og de enkelte temaer
await addr.dagi.lookup({ lat: 55.68, lon: 12.55 });
await addr.dagi.politikreds('1471');
await addr.dagi.sogne();

// Postnumre + vejnavne
await addr.postnumre.list({ q: '2100' });
await addr.vejnavne.search({ q: 'storegade' });

// Reference-data
await addr.reference.jordstykker();
await addr.reference.bebyggelse('id');

// Geo — adgangsadresser i et område
await addr.geo.naermeste({ lat: 55.68, lon: 12.55, limit: 10 });
await addr.geo.indenForRadius({ lat: 55.68, lon: 12.55, radiusM: 500 });
await addr.geo.indenForBbox({ syd: 55.6, vest: 12.5, nord: 55.7, oest: 12.6 });

// Statistik
await addr.stats.totals();
await addr.stats.kommuner({ limit: 10 });

Bemærk: der findes ingen kommuneliste under /v1. Brug dagi.lookup() for kommunen ved et punkt eller postnummer, stats.kommuner() for tal pr. kommune, eller GET /dawa/kommuner for den fulde liste med geometri.

Streaming-iteratorer

// Iterér ALLE matched adresser (auto-pagineret)
for await (const adresse of addr.adresser.all({ kommunekode: '0101' })) {
  process(adresse);
}

// Replikering — event-stream
let cursor = 0;
for await (const event of addr.replikering.adresser.iterate({ cursor })) {
  applyEvent(event);
  cursor = event.sekvensnummer;  // gem cursor lokalt for resume
}

Bulk-opslag

Flere id'er i ét kald (kræver Pro eller derover):

const bygninger = await addr.bbr.bygninger.batch(['1234567890', '0987654321']);
const enheder   = await addr.bbr.enheder.batch(['1111111111']);
const omraader  = await addr.dagi.lookupBatch([
  { lat: 55.6761, lon: 12.5683, id: 'kbh' },
  { lat: 56.1629, lon: 10.2039, id: 'aarhus' },
]);

Batch-jobs (upload af en hel adressefil med opfølgende status og download) er en funktion i dashboardet på danskadresseapi.dk, ikke i API'et. Den kan ikke drives med en API-nøgle og indgår derfor ikke i dette SDK.

Webhook-verify

Separat sub-export så React-bundlere ikke fanger Node-crypto:

// Next.js API-route eller Express handler
import { verifyWebhook } from 'danskadresseapi-sdk/webhooks';

export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get('x-addr-signature') ?? '';
  if (!verifyWebhook(raw, sig, process.env.WEBHOOK_SECRET!)) {
    return new Response('Invalid signature', { status: 401 });
  }
  // ...behandl event
}

Algoritmen er HMAC-SHA256 over ${unix_t}.${rawBody} med endpoint-secret. Replay-protection: 5 min default tolerance (override via { toleranceSeconds }).

React hooks

import { useAutocomplete } from 'danskadresseapi-sdk/react';
import { Addr } from 'danskadresseapi-sdk';

// Cache client mellem renders
const addr = new Addr({ apiKey: process.env.NEXT_PUBLIC_ADDR_KEY! });

export function AddressInput() {
  const [q, setQ] = useState('');
  const { results, loading, error } = useAutocomplete(q, {
    client: addr,
    debounceMs: 150,
    limit: 6,
  });

  return (
    <>
      <input value={q} onChange={(e) => setQ(e.target.value)} />
      {loading && <span>Søger...</span>}
      {error && <span>{error.message}</span>}
      <ul>{results.map(r => <li key={r.data.id}>{r.tekst}</li>)}</ul>
    </>
  );
}

Konfiguration

new Addr({
  apiKey: 'sk_live_…',
  baseUrl: 'https://api.danskadresseapi.dk',  // default
  timeoutMs: 10_000,                          // default
  retries: 1,                                 // 5xx/netværk auto-retries
  userAgentSuffix: 'my-app/1.0.0',            // tilføjes efter "danskadresseapi-sdk/X.Y.Z"
});

Errors

import { Addr, AddrError } from 'danskadresseapi-sdk';

try {
  await addr.autocomplete({ q: 'x' });
} catch (err) {
  if (err instanceof AddrError) {
    console.log(err.type, err.status, err.requestId);
    // type: 'unauthorized' | 'forbidden' | 'not_found' | 'rate_limited' | ...
  }
}

Migration fra DAWA

Kommer du fra DAWA, er dette SDK sandsynligvis ikke det du skal bruge.

/dawa/* serveres af DAWA's egen motor og spejler dens URL-struktur og JSON-form 1:1. Din eksisterende kode taler allerede det sprog — skift base-URL fra https://api.dataforsyningen.dk til https://api.danskadresseapi.dk/dawa, tilføj din nøgle, og du er færdig. Ingen nye afhængigheder, ingen omskrivning.

- const res = await fetch('https://api.dataforsyningen.dk/adresser?q=Nørrebrogade');
+ const res = await fetch('https://api.danskadresseapi.dk/dawa/adresser?q=Nørrebrogade', {
+   headers: { Authorization: `Bearer ${process.env.ADDR_KEY}` },
+ });

Dette SDK dækker /v1 — vores eget API med envelope-svar, felt-filtrering og webhooks. Vælg det, hvis du bygger nyt og ikke er bundet af DAWA-formatet. De to flader har med vilje forskellige svarformer, så SDK'et spejler ikke /dawa.

Se /docs/dawa for den fulde DAWA-reference.

License

MIT