Grundlegende Antworten zur Adressvalidierung

Die Address Validation API stellt einen Antworttext als JSON-Objekt bereit, das zwei Top-Level-Properties enthält:

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

In diesem Dokument geht es um das result-Objekt. Weitere Informationen zu responseID finden Sie unter Aktualisierte Adressen verarbeiten.

Das verdict-Attribut

Das Attribut verdict fasst die Ergebnisse der Adressvalidierung zusammen und sollte das erste Attribut sein, das beim Erstellen einer Logik zur Adressprüfung ausgewertet wird. Je nach Qualität der Ausgabeadresse kann die Property verschiedene Felder zurückgeben. Im folgenden Beispiel wird beispielsweise die verdict-Eigenschaft einer Adresse mit guter Qualität gezeigt, die für diese Anfrage vier Felder zurückgibt:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

In den folgenden Abschnitten werden alle Felder des Attributs verdict zusammengefasst.

Weitere Informationen finden Sie im Leitfaden unter Urteil.

Detaillierungsgrad der Adresse

Der Detaillierungsgrad von Adressen bezieht sich auf den Detaillierungsgrad, mit dem die Spezifität einer Adresse oder eines Geocodes bestimmt wird. Die Adressspezifität in der validationGranularity-Antwort ist ein wichtiges Signal dafür, ob eine Adresse zustellbar ist.

Die Property verdict gibt folgende Detaillierungssignale zurück:

  • inputGranularity: Gibt die Detailebene an, die aus der Adresse erfasst und an die Address Validation API gesendet wurde. Der Detaillierungsgrad der Adresse in der Anfrage wirkt sich auf den Detaillierungsgrad in der Validierungsantwort aus. Eine Adresse mit einer inputGranularity unter einer PREMISE führt beispielsweise in der Regel nicht zu einer validationGranularity bis PREMISE.
  • validationGranularity: Die Detailebene, bis zu der die Address Validation API die Adresse vollständig validieren kann. In den meisten Fällen weist eine Detailebene von PREMISE oder SUB_PREMISE auf eine hochwertige Adresse hin, die wahrscheinlich zugestellt werden kann.
  • geocodeGranularity: Gibt die Detailgenauigkeit des Geocodes an, der mit der Adresse verknüpft ist. So kann aus den Google-Datensätzen beispielsweise hervorgehen, dass es eine Wohnungsnummer gibt, aber nicht den genauen Standort für diese bestimmte Wohnung in einem großen Wohnkomplex. In diesem Fall ist die validationGranularity SUB_PREMISE, aber die geocodeGranularityisPREMISE.
Weitere Informationen finden Sie im Leitfaden unter Detaillierungsgrad.

Vollständigkeit der Adresse

Das Urteil gibt das Attribut addressComplete als Signal für eine Adresse mit hoher Qualität zurück. Das bedeutet konkret, dass keine fehlenden, nicht aufgelösten oder unerwarteten Komponenten vorhanden sind:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

Wenn die Adresse fehlende, nicht aufgelöste oder unerwartete Komponenten enthält, wird das Feld auf false gesetzt.

Weitere Informationen finden Sie im Leitfaden unter addressComplete unter Urteil und Adresse.

Qualität der Adresse

Eine Reihe möglicher Felder geben entweder Probleme mit Adresskomponenten oder Anpassungen an ihnen an, z. B. abgeleitete oder fehlende Adresskomponenten. Die folgende verdict-Eigenschaft gibt beispielsweise eine Adresse mit nicht bestätigten Komponenten und einem fehlenden addressComplete-Feld an:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
Weitere Informationen finden Sie im Leitfaden unter Urteil.

Die Properties address und addressComponent

Die Property address enthält die Formatierung der in der Anfrage angegebenen verarbeiteten Adresse sowie Zusammenfassungen der Adresse auf Komponentenebene, einschließlich falsch geschriebener Teile der Adresse, ersetzter falscher Teile und abgeleiteter fehlender Teile.

Weitere Informationen finden Sie im Leitfaden unter Address.

Das Attribut addressComponent ist eine untergeordnete Komponente von address, die eine detaillierte Auflistung der Elemente oder Komponenten der Adresse enthält, die von der Address Validation API verarbeitet wurden. Die API identifiziert jedes Komponentenfeld anhand seines Namens, Typs und seiner Bestätigungsstufe.

Weitere Informationen findest du im Referenzleitfaden unter addressComponent.

Das geocode-Attribut

Die Property geocode gibt den geocodierten Standort an, der mit der eingegebenen Adresse verknüpft ist. Dieses Attribut enthält Details zum Ort selbst, z. B. die Orts-ID.

Weitere Informationen finden Sie im Leitfaden unter Geocode.

Das Attribut metadata

Dieses Attribut wird möglicherweise nicht für jede Adresse ausgefüllt, die von der Address Validation API verarbeitet wird, gibt aber an, ob die Adresse vom Typ „Wohn“, „Unternehmen“ oder ein Postfach ist.

Weitere Informationen finden Sie unter Abdeckung der Address Validation API und in der Referenz für Address metadata.

Das uspsData-Attribut

Diese Property enthält nützliche Informationen für Postadressen in den USA. Es ist jedoch nicht garantiert, dass es für jede vom Dienst validierte Adresse vollständig ausgefüllt ist. Aus diesem Grund sollten Sie sich nicht nur auf dieses Attribut verlassen, um Adressen zu validieren, sondern auch verdict und address prüfen.

Weitere Informationen findest du unter Umgang mit US-Adressen und in der Referenz zu UspsData.
Zurück
Anfrage zur Adressbestätigung senden
Weiter
Validierungslogik erstellen