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.

Das verdict-Attribut

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. 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 des Attributs verdict zusammengefasst.

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 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. Der Detaillierungsgrad der Adresse in der Anfrage wirkt sich auf den Detaillierungsgrad in der Validierungsantwort aus. Eine Adresse mit einer inputGranularity unter einer PREMISE führt beispielsweise in der Regel nicht zu einer validationGranularity bis PREMISE.
• validationGranularity: Die Detailebene, bis zu 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. 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 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
}

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

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
}

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.

Das geocode-Attribut

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

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.

Das uspsData-Attribut

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.