Country Data API

Postleitzahlformat

Validieren Sie das Postleitzahlfeld ohne Serveraufruf

Postleitzahlen sehen von Land zu Land völlig unterschiedlich aus: fünf Ziffern in Spanien, SW1A 1AA im Vereinigten Königreich, K1A 0B1 in Kanada. Der Endpunkt /v1/places/postal-format liefert Ihnen Format, offiziellen regulären Ausdruck und einen Beispielwert pro Land, damit Ihr Formular das Feld im Browser validieren und einen sinnvollen Platzhalter anzeigen kann.

Endpunkt

GET https://api.countrydataapi.com/v1/places/postal-format

Query-Parameter

Parameter Typ Erforderlich Beschreibung
apikey string Ja Ihr API-Authentifizierungsschlüssel
country string Nein Interne ID, ISO-2, ISO-3 oder Name. Weglassen, um alle Länder zu erhalten
lang string Nein Sprache der Ländernamen. Standard: en

Anfragebeispiel

curl "https://api.countrydataapi.com/v1/places/postal-format?apikey=ihr-api-schluessel&country=ES&lang=de"

Alle Länder einmal abrufen und zwischenspeichern

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/postal-format?apikey=ihr-api-schluessel&lang=de'
);
const { data } = await response.json();

// Nach ISO-2 indizieren, für sofortige Zugriffe im Formular
const formats = Object.fromEntries(
  data.map(({ country, postal }) => [country.iso2, postal])
);

localStorage.setItem('postal_formats', JSON.stringify(formats));

TypeScript-SDK

const { data } = await api.places.postalFormat({ country: 'ES' });
data[0].postal.regex; // "^\\d{5}$"

Antwortformat

{
  "success": true,
  "data": [
    {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Spanien",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "postal": {
        "format": "#####",
        "regex": "^\\d{5}$",
        "example": "12345"
      }
    }
  ],
  "count": 1,
  "tokens_used": 1,
  "remaining_tokens": 4869
}

Die Vorlage format

Symbol Bedeutung
# Eine Ziffer
@ Ein Buchstabe
alles andere Ein wörtliches Zeichen (Leerzeichen, Bindestrich, Länderpräfix ...)

@@# #@@ beschreibt also eine britische Postleitzahl und erzeugt das Beispiel AB1 2CD.

example wird aus format erzeugt und anschließend gegen regex geprüft. Passen beide nicht zusammen, ist example gleich null statt eines erfundenen Werts, auf den Sie sich nicht verlassen können. Länder ohne Postsystem liefern in allen drei Feldern null.

Verwendung in einem Formular

function validatePostcode(value, iso2) {
  const postal = formats[iso2];
  if (!postal?.regex) return true; // kein Muster hinterlegt: alles akzeptieren
  return new RegExp(postal.regex).test(value.trim());
}

// Dient auch als Platzhalter
input.placeholder = formats[iso2]?.example ?? '';

Die Validierung im Browser verbessert die Bedienung, sie ist keine Garantie. Eine wohlgeformte Postleitzahl ist nicht zwangsläufig eine echte: Bestätigen Sie sie mit /v1/places/validate, bevor Sie etwas dorthin versenden.

Token-Verbrauch

1 Token pro Anfrage, egal ob Sie ein Land oder alle abfragen.

Diese Daten ändern sich kaum. Rufen Sie die vollständige Liste einmal ab, speichern Sie sie zwischen, und Sie brauchen diesen Endpunkt monatelang nicht wieder. Sie dürfen sie beliebig lange aufbewahren.

Verwandte Endpunkte