Grundlegende Antworten zur Adressvalidierung

Die Antwort der Address Validation API enthält die folgenden Attribute auf oberster Ebene:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

Das Attribut verdict

Das Attribut verdict fasst die Ergebnisse der Address Validation zusammen und sollte das erste Attribut sein, das beim Erstellen der Logik für die Adressprüfung ausgewertet wird. Die Property kann je nach Qualität der Ausgabeadresse verschiedene Felder zurückgeben. Im Folgenden sehen Sie beispielsweise das Attribut verdict einer Adresse von guter Qualität, das für diese bestimmte Anfrage die folgenden Felder zurückgibt:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

In den folgenden Abschnitten werden alle Felder im Attribut verdict zusammengefasst.

Detaillierungsgrad der Adresse

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

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

• inputGranularity: Gibt den Detaillierungsgrad der Adresse an, die an die Address Validation in der Maps JavaScript API gesendet wurde. Der Detaillierungsgrad der Adresse in der Anfrage beeinflusst den Detaillierungsgrad der Adresse in der Validierungsantwort. Eine Adresse mit einem inputGranularity unter PREMISE führt beispielsweise in der Regel nicht zu einem validationGranularity auf einer PREMISE-Ebene.
• validationGranularity: Der Granularitätsgrad, bis zu dem die Address Validation in der Maps JavaScript API die Adresse vollständig validieren kann. In den meisten Fällen weist ein Granularitätsgrad von PREMISE oder SUB_PREMISE auf eine hochwertige Adresse hin, die wahrscheinlich zustellbar ist.
• geocodeGranularity: Beschreibt den Detaillierungsgrad des Geocodes, der mit der Adresse verknüpft ist. Beispielsweise kann in den Google-Datensätzen eine Wohnungsnummer vorhanden sein, aber kein genauer Standort für diese bestimmte Wohnung innerhalb eines großen Wohnkomplexes. In diesem Fall ist der validationGranularity SUB_PREMISE, aber der geocodeGranularity ist PREMISE.

Vollständigkeit der Adresse

Das Ergebnis gibt das Attribut addressComplete als Signal für eine hochwertige Adresse zurück. Das bedeutet insbesondere, 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.

Adressqualität

Eine Reihe möglicher Felder weisen entweder auf Probleme mit Adresskomponenten oder auf Anpassungen hin, z. B. abgeleitete oder fehlende Adresskomponenten. Die folgende verdict-Property gibt beispielsweise eine Adresse mit unbestätigten Komponenten und einem fehlenden addressComplete-Feld an:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Mögliche nächste Aktion

Das Ergebnisfeld possibleNextAction bietet eine interpretative Zusammenfassung der API-Antwort, die Ihnen bei der Entscheidung helfen soll, welche nachfolgende Aktion Sie ergreifen sollten. Dieses Feld wird von anderen Feldern in der API-Antwort abgeleitet und sollte nicht als Garantie für die Richtigkeit oder Zustellbarkeit der Adresse angesehen werden.

Die Properties address und addressComponent

Das Attribut address enthält die Formatierung für die verarbeitete Adresse, die in der Anfrage angegeben wurde, 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 Unterkomponente von address, die eine detaillierte Liste der Elemente oder Komponenten der Adresse enthält, die von der Address Validation in der Maps JavaScript API verarbeitet wurden. Die API identifiziert jedes von einem Feld bereitgestellte Komponentenfeld anhand seines Namens, Typs und Bestätigungsgrads.

Das Attribut geocode

Die Property geocode gibt den geocodierten Standort an, der der Eingabeadresse zugeordnet ist. Diese Property enthält Details zum Ort selbst, z. B. die Orts-ID.

Das Attribut metadata

Diese Property wird möglicherweise nicht für jede Adresse ausgefüllt, die von der Adressvalidierung in der Maps JavaScript API verarbeitet wird. Sie gibt jedoch an, ob es sich bei der Adresse um eine Privat- oder Geschäftsadresse oder ein Postfach handelt.

Das Attribut uspsData

Diese Property liefert nützliche Informationen zu Postadressen in den USA. Es ist jedoch nicht garantiert, dass es für jede vom Dienst validierte Adresse vollständig ausgefüllt ist. Daher sollten Sie sich nicht allein auf diese Eigenschaft verlassen, um Adressen zu validieren, sondern auch verdict und address prüfen.