Grundlegende Antworten zur Adressvalidierung

Die Address Validation API stellt einen Antworttext als JSON-Objekt bereit, das zwei übergeordnete Attribute 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. Informationen zu responseID finden Sie unter Umgang mit aktualisierten Adressen.

Das Attribut verdict

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. Das Attribut kann je nach Qualität der Ausgabeadresse verschiedene Felder zurückgeben. Im folgenden Beispiel ist das Attribut verdict einer Adresse von guter Qualität zu sehen, die vier Felder für diese bestimmte Anfrage zurückgibt:

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

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

Siehe Verdikt im Referenzleitfaden.

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 lieferbar ist.

Das Attribut verdict gibt diese Granularitätssignale zurück:

  • inputGranularity: Beschreibt die Detailgenauigkeit, die von der an die Address Validation API gesendeten Adresse erfasst wird. Der Detaillierungsgrad der Adresse in der Anfrage wirkt sich auf den Detaillierungsgrad in der Validierungsantwort aus. Beispielsweise führt eine Adresse mit einem inputGranularity unter PREMISE normalerweise nicht zu einem validationGranularity bis PREMISE.
  • validationGranularity: Der Detaillierungsgrad, für den die Address Validation API die Adresse vollständig validieren kann. In den meisten Fällen weist ein Detaillierungsgrad von PREMISE oder SUB_PREMISE auf eine qualitativ hochwertige Adresse hin, mit der ein Liefergegenstand wahrscheinlich ist.
  • geocodeGranularity: Beschreibt die Detailgenauigkeit des mit der Adresse verknüpften Geocodes. 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 validationGranularity SUB_PREMISE, aber geocodeGranularityisPREMISE.
Weitere Informationen finden Sie im Referenzleitfaden unter Detaillierungsgrad.

Vollständigkeit der Adresse

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

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

Wenn in der Adresse fehlende, nicht aufgelöste oder unerwartete Komponenten fehlen, wird das Feld auf false gesetzt.

Siehe addressComplete unter Urteil und Adresse im Referenzleitfaden.

Adressqualität

Eine Reihe möglicher Felder weist entweder auf Probleme mit Adresskomponenten oder auf Korrekturen an ihnen hin, z. B. abgeleitete oder fehlende Adresskomponenten. Das folgende Attribut verdict gibt beispielsweise eine Adresse mit nicht bestätigten Komponenten und einem fehlenden Feld addressComplete an:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
Siehe Verdikt im Referenzleitfaden.

Die Attribute address und addressComponent

Das Attribut address bietet die Formatierung der verarbeiteten Adresse aus der Anfrage sowie Zusammenfassungen der Adresse auf Komponentenebene, einschließlich falsch geschriebener Teile der Adresse, Ersatz falscher Teile und abgeleiteter fehlender Teile.

Siehe Address im Referenzleitfaden.

Das Attribut addressComponent ist eine Unterkomponente von address. Sie bietet eine detaillierte Liste der Elemente oder Komponenten der Adresse, die von der Address Validation API verarbeitet wurde. Die API identifiziert jedes Komponentenfeld anhand des Namens, des Typs und der Bestätigungsebene.

Siehe addressComponent im Referenzleitfaden.

Das Attribut geocode

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

Siehe Geocode im Referenzleitfaden.

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 zu Address metadata.

Das Attribut uspsData

Diese Eigenschaft bietet nützliche Informationen zu Postanschriften in den USA. Es kann jedoch nicht garantiert werden, dass er für jede vom Dienst validierte Adresse vollständig ausgefüllt wird. Aus diesem Grund sollten Sie sich zum Validieren von Adressen nicht auf dieses Attribut verlassen, 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