Grundlegende Antworten zur Adressvalidierung

Hinweis :In diesem Dokument werden die grundlegenden Elemente einer Antwort zur Adressvalidierung für eine Adresse mit hoher Qualität beschrieben. Informationen zum Arbeiten mit realen Adressszenarien und zum Erstellen von Logik für komplexere Antworten finden Sie unter Validierungslogik erstellen.

Die Address Validation API gibt einen Antworttext als JSON-Objekt zurück, der zwei Eigenschaften der obersten Ebene enthält:

• result, ein Objekt vom Typ ValidationResult
• responseID

{
  "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 zum responseID finden Sie unter Aktualisierte Adressen verarbeiten.

Die verdict-Property

Wichtiger Hinweis: Mit dem Attribut verdict erhalten Sie eine grundlegende Zusammenfassung der Qualität der Adresse.

Die Eigenschaft verdict fasst die Ergebnisse der Adressvalidierung zusammen und sollte die erste Eigenschaft sein, die bei der Entwicklung der Logik zur Adressprüfung ausgewertet wird. Je nach Qualität der Ausgabeadresse kann die Property verschiedene Felder zurückgeben. Im Folgenden sehen Sie beispielsweise die verdict-Eigenschaft einer Adresse mit guter Qualität, die für diese spezielle Anfrage vier Felder zurückgibt:

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

In den folgenden Abschnitten werden alle Felder der Property verdict zusammengefasst.

Weitere Informationen finden Sie im Referenzleitfaden unter Verdict.

Mögliche nächste Schritte

Die Eigenschaft possibleNextAction bietet eine zusammenfassende Interpretation des Rests der API-Antwort. Sie soll Ihnen dabei helfen, zu entscheiden, ob Sie Ihren Kunden auffordern sollten, seine Adresse zu überprüfen oder zu bearbeiten. Weitere Informationen finden Sie unter Validierungslogik erstellen.

Detaillierungsgrad der Adresse

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

Die verdict-Property gibt die folgenden Granularitätssignale zurück:

• inputGranularity: Beschreibt die Detailebene der Adresse, die an die Address Validation API gesendet wurde. Die Detailgenauigkeit der Adresse in der Anfrage beeinflusst die Detailgenauigkeit der Adresse in der Validierungsantwort. Eine Adresse mit einem inputGranularity unter PREMISE führt in der Regel nicht zu einer validationGranularity auf PREMISE-Ebene.
• validationGranularity: Die Granularitätsebene, bis zu der die Address Validation API die Adresse vollständig validieren kann. In den meisten Fällen weist eine Granularität von PREMISE oder SUB_PREMISE auf eine hochwertige Adresse hin, die wahrscheinlich zustellbar ist.
• geocodeGranularity: Beschreibt die Detailgenauigkeit des Geocodes, der der Adresse zugeordnet ist. So kann es beispielsweise sein, dass in den Google-Aufzeichnungen eine Wohnungsnummer angegeben ist, aber nicht der genaue Standort dieser Wohnung in einem großen Wohnkomplex. In diesem Fall ist die validationGranularity SUB_PREMISE, aber die geocodeGranularityisPREMISE`.

Weitere Informationen finden Sie im Referenzleitfaden unter Granularität.

Vollständigkeit der Adresse

Das Ergebnis gibt das Attribut addressComplete als Signal für eine hochwertige Adresse zurück. Das bedeutet, dass keine Komponenten fehlen, nicht aufgelöst oder unerwartet sind:

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

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

Hinweis :Wenn das Attribut addressComplete bei der manuellen Überprüfung nicht im Urteil enthalten ist, lautet sein Wert „false“. Je nach Programmiersprache fragen Sie entweder das Ergebnis nach dem Vorhandensein des Attributs addressComplete ab oder fragen das Attribut direkt ab. Beispiel

Weitere Informationen finden Sie im Referenzleitfaden unter addressComplete im Abschnitt Verdict (Urteil) und Address (Adresse).

Adressqualität

Eine Reihe möglicher Felder weist entweder auf Probleme mit Adresskomponenten oder auf Anpassungen an ihnen hin, 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 Referenzleitfaden unter Verdict.

Die Properties address und addressComponent

Wichtiger Hinweis :Verwenden Sie die Property address, um die Adressformatierung abzurufen. Verwenden Sie die Unterkomponente addressComponent, um Fehler zu untersuchen und Ihren Kunden Informationen zu diesen Fehlern zu geben. Sie sollten Ihre Integration jedoch nicht so gestalten, dass sie auf der spezifischen Bestätigungsstufe für Adresskomponenten basiert. Weitere Informationen zur Integration finden Sie unter Validierungslogik erstellen.

Das Attribut address enthält die Formatierung für die in der Anfrage angegebene verarbeitete 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 Referenzleitfaden unter Address.

Das Attribut addressComponent ist eine Unterkomponente von address, die eine detaillierte Liste 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 Bestätigungsgrads.

Weitere Informationen finden Sie im Referenzleitfaden unter addressComponent.

Die geocode-Property

Wichtiger Hinweis :Verwenden Sie das Attribut geocode, um den Geocode oder die Orts-ID abzurufen, wenn in Ihrer Logik zuvor die Geocoding API aufgerufen wurde.

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

Weitere Informationen finden Sie im Referenzleitfaden unter Geocode.

Die metadata-Property

Wichtiger Hinweis: Mit dem Attribut metadata können Sie den Typ der mit der Adresse verknüpften Immobilie ermitteln: Wohngebäude, Postfach oder Geschäftsgebäude.

Dieses Attribut wird möglicherweise nicht für jede von der Address Validation API verarbeitete Adresse ausgefüllt. Es gibt jedoch an, ob es sich bei der Adresse um eine Privat-, Geschäfts- oder Postfachadresse handelt.

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

Die uspsData-Property

Hinweis :Mit der Eigenschaft uspsData können Sie Informationen zur Wahrscheinlichkeit der Zustellung und andere USPS-Details zu US-Adressen abrufen.

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 ausschließlich auf diese Property verlassen, um Adressen zu validieren, sondern auch verdict und address prüfen.

Weitere Informationen finden Sie unter Adressen in den USA verarbeiten und in der Referenz für UspsData.