JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 176
  • Score
    100M100P100Q76607F
  • License MIT

TypeScript client voor de adresaanvuller.nl API - zoek en autocomplete Nederlandse adressen

Package Exports

  • adresaanvuller
  • adresaanvuller/react

Readme

adresaanvuller

TypeScript client voor de adresaanvuller.nl API. Zoek en autocomplete Nederlandse adressen op basis van het BAG (Basisregistratie Adressen en Gebouwen).

  • Werkt in de browser en Node.js (18+)
  • Inclusief React hook met debounce en state management
  • Volledig getypt met TypeScript
  • ESM en CommonJS support

Installatie

npm install adresaanvuller

Snel starten

Vanilla TypeScript / JavaScript

import { AdresAanvuller } from 'adresaanvuller';

const client = new AdresAanvuller({ apiKey: 'jouw-api-key' });

const results = await client.search('Hoofdstraat 1 Amsterdam');

console.log(results);
// [
//   {
//     adresregel: "Hoofdstraat 1",
//     postcode_woonplaats: "1234AB Amsterdam",
//     straat: "Hoofdstraat",
//     huisnummer: "1",
//     postcode: "1234AB",
//     woonplaats: "Amsterdam",
//     ...
//   }
// ]

React

import { useAdresAanvuller } from 'adresaanvuller/react';

function AddressSearch() {
  const {
    query,
    setQuery,
    results,
    selectAddress,
    selectedAddress,
    isLoading,
    error,
  } = useAdresAanvuller({
    apiKey: 'jouw-api-key',
  });

  return (
    <div>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Zoek een adres..."
      />

      {isLoading && <span>Laden...</span>}
      {error && <span>{error}</span>}

      {results.map((result) => (
        <div key={result.bag_id} onClick={() => selectAddress(result)}>
          {result.adresregel} - {result.postcode_woonplaats}
        </div>
      ))}

      {selectedAddress && (
        <p>Geselecteerd: {selectedAddress.volledigAdres}</p>
      )}
    </div>
  );
}

API

AdresAanvuller

De headless API client.

const client = new AdresAanvuller(config);

Config

Parameter Type Verplicht Beschrijving
apiKey string Ja API key voor authenticatie
apiUrl string Nee Custom API URL (standaard: https://api.adresaanvuller.nl/search)

client.search(query, options?)

Zoek naar adressen.

Parameter Type Beschrijving
query string Zoekterm (bijv. "Hoofdstraat 1", "1234AB")
options.lockedWoonplaats string Beperk resultaten tot een woonplaats
options.exactStreet boolean Zoek exact op straatnaam

Retourneert: Promise<AdresResult[]>

useAdresAanvuller (React hook)

React hook met ingebouwde debounce, state management en woonplaats-locking.

const {
  query,              // Huidige zoekterm
  setQuery,           // Update zoekterm (triggert automatisch zoeken)
  results,            // Zoekresultaten
  isLoading,          // Laadstatus
  error,              // Foutmelding of null
  selectedAddress,    // Geselecteerd adres of null
  selectAddress,      // Selecteer een adres uit resultaten
  clear,              // Wis alles
  lockedWoonplaats,   // Gelocked woonplaats of null
  lockWoonplaats,     // Lock op een woonplaats
  unlockWoonplaats,   // Verwijder de lock
} = useAdresAanvuller(config);

Config

Parameter Type Verplicht Standaard Beschrijving
apiKey string Ja - API key voor authenticatie
apiUrl string Nee https://api.adresaanvuller.nl/search Custom API URL
debounceTime number Nee 300 Debounce in ms
minLength number Nee 2 Minimum karakters voor zoeken

Types

interface AdresResult {
  adresregel: string;           // "Hoofdstraat 1A"
  postcode_woonplaats: string;  // "1234AB Amsterdam"
  straat: string;               // "Hoofdstraat"
  huisnummer: string;           // "1"
  huisletter: string;           // "A"
  huisnummertoevoeging: string; // ""
  postcode: string;             // "1234AB"
  woonplaats: string;           // "Amsterdam"
  oppervlakte: number;          // 85
  bag_id: string;               // BAG identificatie
  isStreet?: boolean;           // true als het een straat is
  isCity?: boolean;             // true als het een woonplaats is
}

interface SelectedAddress {
  straat: string;
  huisnummer: string;
  huisletter: string;
  huisnummertoevoeging: string;
  postcode: string;
  woonplaats: string;
  oppervlakte: number;
  volledigAdres: string;        // Volledige adresregel
}

Woonplaats locking

De React hook ondersteunt het "locken" van zoekresultaten op een specifieke woonplaats. Dit is handig als een gebruiker eerst een woonplaats selecteert en daarna een straat zoekt:

const { lockWoonplaats, unlockWoonplaats, lockedWoonplaats } = useAdresAanvuller({
  apiKey: 'jouw-api-key',
});

// Lock op Amsterdam
lockWoonplaats('Amsterdam');

// Verwijder de lock
unlockWoonplaats();

Error handling

import { AdresAanvuller, AdresAanvullerError } from 'adresaanvuller';

const client = new AdresAanvuller({ apiKey: 'jouw-api-key' });

try {
  const results = await client.search('test');
} catch (error) {
  if (error instanceof AdresAanvullerError) {
    console.error(error.message);     // Foutmelding
    console.error(error.statusCode);  // HTTP status code
    console.error(error.details);     // Extra details
  }
}

Licentie

MIT