Grundlegende Antworten zur Adressvalidierung

Die Address Validation API bietet einen Antworttext als JSON-Objekt, das zwei Attribute auf oberster Ebene 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 findest du unter Aktualisierte Adressen verarbeiten.

Das Attribut verdict

Das Attribut verdict fasst die Ergebnisse der Adressüberprüfung zusammen und sollte beim Erstellen einer Logik für die Adressprüfung die erste Eigenschaft sein, die ausgewertet wird. Das Attribut kann je nach Qualität der Ausgabeadresse eine Vielzahl von Feldern zurückgeben. Das folgende Beispiel zeigt das Attribut verdict einer Adresse von guter Qualität, 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 im Attribut verdict zusammengefasst.

Weitere Informationen finden Sie im Referenzleitfaden unter Verdikt.

Detaillierungsgrad der Adresse

Der Detaillierungsgrad einer Adresse bezieht sich auf die Detailebene, die verwendet wird, um die Spezifität einer Adresse oder eines Geocodes zu bestimmen. Die Adressspezifität in der validationGranularity-Antwort ist ein wichtiges Signal dafür, ob eine Adresse lieferbar ist oder nicht.

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

  • inputGranularity: Beschreibt die Detailebene, die von der an die Address Validation API gesendeten Adresse erfasst wird. Die Detailebene der Adresse in der Anfrage wirkt sich auf die Detailebene in der Validierungsantwort aus. Beispielsweise führt eine Adresse mit einer inputGranularity unter PREMISE unter der Ebene nicht in der Regel zu einem validationGranularity auf eine PREMISE-Ebene.
  • validationGranularity: Die Granularitätsstufe, bis zu der 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, die wahrscheinlich lieferbar ist.
  • geocodeGranularity: Beschreibt die Detailebene des mit der Adresse verknüpften Geocodes. So können Google-Einträge beispielsweise auf das Vorhandensein einer Wohnungsnummer hinweisen, aber keinen genauen Standort für diese bestimmte Wohnung in einem großen Apartmentkomplex. 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 von 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 die Adresse fehlende, nicht aufgelöste oder unerwartete Komponenten enthält, wird das Feld auf false gesetzt.

Weitere Informationen finden Sie im Referenzleitfaden unter Verdikt und Adresse unter addressComplete.

Adressqualität

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

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

Die Attribute address und addressComponent

Das Attribut address stellt die Formatierung für die in der Anfrage angegebene verarbeitete Adresse bereit. Außerdem werden Zusammenfassungen der Adresse auf Komponentenebene bereitgestellt, darunter falsch geschriebene Teile der Adresse, Ersatz falsch geschriebener Teile und abgeleiteter fehlender Teile.

Weitere Informationen finden Sie im Referenzleitfaden unter Address.

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

Weitere Informationen finden Sie im Referenzleitfaden unter addressComponent.

Das Attribut geocode

Das Attribut geocode gibt den geocodierten Standort der Eingabeadresse an. Dieses Attribut enthält Details zum Standort selbst, z. B. die Orts-ID.

Weitere Informationen finden Sie im Referenzleitfaden unter Geocode.

Das Attribut metadata

Dieses Attribut wird möglicherweise nicht für jede von der Address Validation API verarbeitete Adresse ausgefüllt. Es wird jedoch angegeben, ob es sich um eine Privatadresse, ein Unternehmen oder ein Postfach handelt.

Weitere Informationen finden Sie unter Abdeckung der Address Validation API und in der Referenz zu Address metadata.

Das Attribut uspsData

Diese Property bietet nützliche Informationen zu Postadressen in den USA. Es ist jedoch nicht garantiert, dass er für jede vom Dienst validierte Adresse vollständig ausgefüllt ist. Aus diesem Grund sollten Sie Adressen nicht nur mit diesem Attribut validieren, sondern auch verdict und address.

Weitere Informationen findest du unter Umgang mit Adressen in den USA und in der Referenz zu UspsData.