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. Informationen zur responseID, siehe Umgang mit aktualisierten Adressen.

Das Attribut verdict

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. Die Eigenschaft kann eine Vielzahl von Feldern zurückgeben, abhängig von der Qualität des . Im folgenden Beispiel wird 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 der Adresse bezieht sich auf den Detaillierungsgrad, Spezifität einer Adresse oder eines Geocodes. Die Adressspezifität in der validationGranularity-Antwort ist ein wichtiges Signal dafür, ob eine Adresse zustellbar ist.

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

• inputGranularity: Beschreibt die Detailgenauigkeit, die mithilfe der Adresse, die an die Address Validation API gesendet wird. Der Detaillierungsgrad der Adresse in der -Anfrage beeinflusst den Detaillierungsgrad der Adresse in der Validierungsantwort. Beispiel: Eine Adresse mit einem inputGranularity unter PREMISE unten führt normalerweise nicht zu einem validationGranularity bis PREMISE
• validationGranularity: Der Detaillierungsgrad, den die Die Address Validation API kann die Adresse vollständig validieren. In den meisten Fällen weist eine Detailebene von PREMISE oder SUB_PREMISE auf eine hochwertige Adresse hin, die wahrscheinlich zugestellt werden kann.
• geocodeGranularity: Beschreibt die Detailgenauigkeit des Geocodes die mit der Adresse verknüpft sind. So können Google-Datensätze z. B. angeben, eine Wohnungsnummer vorhanden ist, aber keinen genauen Standort dafür. für eine 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

Das Attribut address formatiert die verarbeitete Adresse, die in der Anfrage zusammen mit Zusammenfassungen der Adresse auf Komponentenebene, einschließlich falsch geschriebene Teile der Adresse; fehlerhafte Teile ersetzt und abgeleitete Informationen fehlen 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 die einzelnen Komponenten nach Name, Typ und Bestätigungsebene bereitstellt.

Das geocode-Attribut

Die Eigenschaft geocode gibt den geocodierten Ort an, der mit der Eingabe verknüpft ist. Adresse. Diese Eigenschaft bietet Details zum Standort selbst, z. B. ihre Orts-ID.

Das Attribut metadata

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.

Das Attribut uspsData

Diese Eigenschaft bietet nützliche Informationen zu Postanschriften 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.