Wie funktioniert eine PLZ-API technisch? [Kompletter Leitfaden]

Eine PLZ-API klingt einfach — Sie senden eine Postleitzahl und Hausnummer und erhalten eine Adresse zurück. Doch dahinter steckt eine Menge Technik. Dieser Leitfaden erklärt alles: von der zugrunde liegenden Datenbank bis zur korrekten Fehlerbehandlung.

Was ist eine PLZ-API?

Eine PLZ-API ist ein Webservice, der eine Postleitzahl (und optional eine Hausnummer) in eine vollständige, strukturierte Adresse umwandelt. Das Ergebnis enthält in der Regel Straßenname, Hausnummer, Ort, Gemeinde, Provinz und GPS-Koordinaten.

Wie funktioniert eine Adresssuche technisch?

1. Eingabe

Der Aufruf enthält mindestens:

• postalcode — die Postleitzahl (z. B. 1092CX)
• number — die Hausnummer (z. B. 12)
• Optional: numberAddition — Hausnummernzusatz (z. B. A)

2. Suche in der Datenbank

Die API sucht in einer aktuellen Kopie der Basisregistratie Adressen en Gebouwen (BAG) — dem offiziellen niederländischen Adressregister. Diese Datenbank enthält alle offiziell registrierten Adressen in den Niederlanden und wird monatlich von der Regierung aktualisiert.

3. Antwort

{
  "street": "Linnaeusstraat",
  "number": 12,
  "numberAddition": "",
  "postalcode": "1092CX",
  "city": "Amsterdam",
  "municipality": "Amsterdam",
  "province": "Noord-Holland",
  "streetShort": "Linnaeusstraat",
  "location": {
    "coordinates": {
      "latitude": 52.3586,
      "longitude": 4.9254
    }
  }
}

Verschiedene Arten von API-Anfragen

Geschwindigkeit und Zuverlässigkeit

Eine gute PLZ-API beantwortet Anfragen innerhalb von 300 Millisekunden. ApiCheck erreicht im Durchschnitt weniger als 100 ms. Das ist schnell genug für den Live-Einsatz in Formularen, ohne spürbare Verzögerung für den Nutzer.

Bei höheren Volumina können Sie Antworten cachen. Beachten Sie: Adressen werden monatlich in der BAG aktualisiert. Eine Cache-Lebensdauer von 7–30 Tagen ist in den meisten Fällen völlig ausreichend.

Fehlerbehandlung

Eine robuste Integration berücksichtigt Fehlerszenarien:

• 404 Not Found: Postleitzahl + Hausnummer existiert nicht. Zeigen Sie dem Nutzer eine Meldung an.
• 422 Unprocessable: Ungültige Eingabe (z. B. falsches Postleitzahlenformat).
• 429 Too Many Requests: Sie haben Ihr Rate-Limit erreicht.
• 503 Service Unavailable: Vorübergehende Störung. Implementieren Sie Retry-Logik mit exponentiellem Backoff.

Beispielimplementierung in PHP

$response = Http::withHeaders([
    'X-Api-Key' => config('services.apicheck.key'),
])->get('https://api.apicheck.nl/lookup/v1/address/nl', [
    'postalcode' => '1092CX',
    'number' => 12,
]);

if ($response->ok()) {
    $address = $response->json();
    echo $address['street']; // Linnaeusstraat
}

Beispielimplementierung in JavaScript

const response = await fetch(
  '/api/validate/address?postalcode=1092CX&number=12'
);
const address = await response.json();
document.getElementById('street').value = address.street;
document.getElementById('city').value = address.city;

Sicherheit

Rufen Sie die API niemals direkt aus dem Browser mit Ihrem echten API-Schlüssel sichtbar im JavaScript-Code auf. Verwenden Sie immer einen serverseitigen Proxy, der:

1. Den Aufruf vom Browser entgegennimmt
2. Ihren echten API-Schlüssel serverseitig hinzufügt
3. Die Antwort an den Browser zurücksendet

Auch ApiChecks eigene Demo-Implementierung funktioniert so — siehe routes/api.php für ein Beispiel.

Häufige Fehler

1. API-Schlüssel im Frontend-JavaScript — niemals tun
2. Kein Fallback bei 404 — der Nutzer steckt fest, wenn die Adresse nicht existiert
3. Cache zu lange aufbewahren — Adressen ändern sich manchmal bei Umnummerierungen
4. Kein Rate-Limiting — manche Nutzer spammen Formulare

Fazit

Eine PLZ-API ist konzeptionell einfach, erfordert aber eine sorgfältige Implementierung für den Produktivbetrieb. Mit einem serverseitigen Proxy, korrekter Fehlerbehandlung und cleverem Caching bauen Sie eine robuste Integration, die jahrelang hält.