Grundlegende Antworten zur Adressvalidierung

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

Die Address Validation API stellt einen Antworttext als JSON-Objekt bereit, das zwei Top-Level-Properties 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. Weitere Informationen zu responseID finden Sie unter Aktualisierte Adressen verarbeiten.

Das verdict-Attribut

Wichtig: Mit dem Attribut verdict erhalten Sie eine zusammenfassende Bewertung der Qualität der Adresse.

Das Attribut verdict fasst die Ergebnisse der Adressvalidierung zusammen und sollte die erste Property sein, die bei der Erstellung der Logik für die 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 der Property verdict zusammengefasst.

Weitere Informationen finden Sie im Leitfaden unter Verdict.

Detaillierungsgrad der Adresse

Die Adressgranularität bezieht sich auf die Detailebene, die zur Bestimmung der Spezifität einer Adresse oder eines Geocodes verwendet 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. Die Detailgenauigkeit der Adresse in der Anfrage wirkt sich auf die Detailgenauigkeit der Adresse in der Validierungsantwort aus. Eine Adresse mit einer inputGranularity unter einer PREMISE führt beispielsweise in der Regel nicht zu einer validationGranularity auf PREMISE-Ebene.
• validationGranularity: Die Detailebene, auf 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. Google-Einträge können beispielsweise die Existenz einer Wohnungsnummer angeben, aber keinen genauen Standort für diese bestimmte Wohnung innerhalb eines großen Wohnkomplexes. 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.

Hinweis: Wenn das Attribut addressComplete bei der manuellen Überprüfung nicht im Urteil aufgeführt ist, ist sein Wert „falsch“. Je nach Programmiersprache können Sie entweder das Urteil auf das Vorhandensein des Attributs addressComplete oder das Attribut direkt abfragen. Ein Beispiel finden Sie unten unter Adressqualität.

Weitere Informationen finden Sie im Leitfaden unter addressComplete unter Verdict 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 Verdict.

Die Properties address und addressComponent

Wichtig :Verwenden Sie die Property address, um die Adressformatierung zu erhalten. Mit der Unterkomponente addressComponent können Sie Fehler untersuchen und Ihren Kunden Informationen zu diesen Fehlern zur Verfügung stellen. Sie sollten Ihre Integration jedoch nicht so gestalten, dass sie auf der spezifischen Bestätigungsebene für Adresskomponenten basiert. Weitere Informationen zur Integration finden Sie unter Validierungslogik erstellen.

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 finden Sie im Leitfaden unter addressComponent.

Das geocode-Attribut

Wichtig: Verwenden Sie das Attribut geocode, um den Geocode oder die Orts-ID abzurufen, wenn Ihre Logik zuvor die Geocoding API aufgerufen hat.

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

Weitere Informationen finden Sie im Leitfaden unter Geocode.

Das metadata-Attribut

Wichtiger Hinweis: Mit dem Attribut metadata können Sie den Typ der mit der Adresse verknüpften Property ermitteln: Privathaus, Postfach oder Unternehmen.

Diese Eigenschaft ist möglicherweise nicht für jede Adresse ausgefüllt, die von der Address Validation API verarbeitet wird. Sie gibt jedoch an, ob es sich um eine Privat-, Geschäfts- oder Postfachadresse handelt.

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

Das uspsData-Attribut

Wichtig :Mit der Property uspsData können Sie Zustellwahrscheinlichkeitsstufen 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 nur auf dieses Attribut 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.