Grundlegende Antworten zur Adressvalidierung

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.

Die verdict-Property

Das Attribut verdict fasst die Ergebnisse der Adressvalidierung zusammen und sollte beim Erstellen der Logik für die Adressprüfung als Erstes ausgewertet werden. 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,
  "possibleNextAction": "ACCEPT"
}

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

Mögliche nächste Aktion

Die Property possibleNextAction bietet eine aussagekräftige Zusammenfassung des Rests der API-Antwort. So kannst du besser entscheiden, ob du deinen Kunden auffordern solltest, seine Adresse zu prüfen oder zu ändern. Weitere Informationen finden Sie unter Validierungslogik erstellen.

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 oder nicht.

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 gibt eine Detailebene von PREMISE oder SUB_PREMISE eine hochwertige Adresse an, 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.

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,
    "possibleNextAction": "ACCEPT"
}

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

Qualität der Adresse

Eine Reihe von möglichen Feldern 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
}

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.

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.

Die geocode-Property

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.

Die metadata-Property

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

Die uspsData-Property

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.