Prüfen Sie, ob eine Adresse existiert, und erhalten Sie sie in kanonischer Form zurück

Der Endpunkt /v1/places/validate nimmt Land, Bundesland, Stadt und Postleitzahl entgegen, die ein Nutzer eingegeben hat, und sagt Ihnen — Komponente für Komponente —, ob diese Kombination tatsächlich existiert. Zurück kommen die kanonische Schreibweise und, wenn etwas nicht passt, die naheliegendste Korrektur.

Es ist der letzte Schritt, bevor Sie eine Lieferadresse speichern: Die Autovervollständigung führt den Nutzer, dies bestätigt, wobei er gelandet ist — auch bei von Hand eingegebenen oder anderswo importierten Adressen.

Endpunkt

GET  https://api.countrydataapi.com/v1/places/validate
POST https://api.countrydataapi.com/v1/places/validate

Beide akzeptieren dieselben Felder. GET ist eine einfache CORS-Anfrage und funktioniert daher ohne Preflight aus dem Browser; POST nimmt sie in einem JSON-Body entgegen.

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`apikey`	string	Ja	Ihr API-Authentifizierungsschlüssel
`country`	string	Ja	Interne ID, ISO-2, ISO-3 oder Name
`state`	string	Nein	Name des Bundeslandes oder der Provinz
`city`	string	Nein	Name der Stadt
`zipcode`	string	Nein	Postleitzahl
`lang`	string	Nein	Sprache der zurückgegebenen Namen. Standard: `en`

Komponenten, die Sie nicht senden, kommen mit dem Urteil not_provided zurück: Nichts, was Sie weglassen, kann die Adresse ungültig machen.

Anfragebeispiel

curl "https://api.countrydataapi.com/v1/places/validate?apikey=ihr-api-schluessel&country=ES&state=Madrid&city=Madrid&zipcode=28001&lang=de"

POST mit JSON-Body

const response = await fetch(
  'https://api.countrydataapi.com/v1/places/validate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apikey: 'ihr-api-schluessel',
      country: 'ES',
      state: 'Madrid',
      city: 'Madrid',
      zipcode: '28001',
      lang: 'de',
    }),
  }
);
const { result } = await response.json();

TypeScript-SDK

const { result } = await api.places.validate({
  country: 'ES',
  zipcode: '28001',
  lang: 'de',
});

result.normalized.state?.name; // "Autonome Gemeinschaft Madrid"

Antwortformat

{
  "success": true,
  "result": {
    "valid": true,
    "has_corrections": false,
    "verdict": {
      "country": "confirmed",
      "state": "confirmed",
      "city": "confirmed",
      "zipcode": "confirmed"
    },
    "normalized": {
      "country": {
        "id": "66c7a6c9e4bda21f4ab10ef2",
        "name": "Spanien",
        "iso2": "ES",
        "iso3": "ESP",
        "phone_code": "+34",
        "flag": "🇪🇸"
      },
      "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Autonome Gemeinschaft Madrid" },
      "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
      "zipcode": "28001"
    },
    "corrections": [],
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345",
      "matches_format": true
    }
  },
  "tokens_used": 1,
  "remaining_tokens": 4870
}

Urteile

Urteil	Bedeutung
`confirmed`	Der Wert existiert und entspricht genau dem Gesendeten
`corrected`	Die Komponente wurde aufgelöst, aber nicht aus dem Gesendeten — siehe `corrections`
`unconfirmed`	Der Wert konnte nicht bestätigt werden
`not_provided`	Sie haben diese Komponente nicht gesendet

valid ist nur dann true, wenn alle von Ihnen gesendeten Komponenten als confirmed zurückkommen. Nutzen Sie has_corrections, um zu entscheiden, ob Sie dem Nutzer ein "Meinten Sie ...?" statt einer Fehlermeldung zeigen.

Eine Postleitzahl allein löst das Bundesland auf

Der übliche Fall im Checkout: Sie haben nur Postleitzahl und Stadt abgefragt.

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

Die Antwort füllt normalized.state aus der Postleitzahl, sodass Sie das Provinzfeld für den Nutzer ausfüllen können, statt danach zu fragen. Umgekehrt funktioniert es genauso: Senden Sie eine Stadt, und das Bundesland kommt aufgelöst zurück.

Wenn die Postleitzahl nicht in unserer Liste steht

Die Abdeckung mit Postleitzahlen ist nicht für jedes Land vollständig. Ist eine Zahl nicht gelistet, entspricht aber dem offiziellen Format des Landes, lautet das Urteil corrected statt unconfirmed, und postal.matches_format ist true. Behandeln Sie das als "plausibel, akzeptieren", sofern Ihr Anwendungsfall keine Gewissheit verlangt.

matches_format ist null, wenn für das Land kein offizielles Muster hinterlegt ist.

Korrekturbeispiel

{
  "valid": false,
  "has_corrections": true,
  "verdict": { "country": "confirmed", "state": "unconfirmed", "city": "confirmed", "zipcode": "not_provided" },
  "corrections": [
    { "component": "state", "input": "Cataluna", "suggestion": "Cataluña" }
  ]
}

Token-Verbrauch

Dieser Endpunkt verbraucht 1 Token pro Anfrage, unabhängig davon, wie viele Komponenten Sie senden.

Adressvalidierung