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 Adressvalidierung zusammen und sollte das erste Attribut sein, das bei der Erstellung der Logik für die Adressprüfung ausgewertet wird. Die Property kann je nach Qualität der Ausgabeadresse eine Vielzahl von Feldern zurückgeben. Im Folgenden sehen Sie beispielsweise das Attribut verdict einer Adresse von guter Qualität, das für diese 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.

Weitere Informationen finden Sie im Referenzhandbuch unter Urteil.

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 einer validationGranularity auf einer PREMISE-Ebene.
  • validationGranularity: Der Detaillierungsgrad, bis zu dem die Adresse mit der Adressvalidierung in der Maps JavaScript API vollständig validiert werden 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-Daten die Existenz einer Wohnungsnummer angegeben sein, aber nicht der genaue Standort dieser Wohnung innerhalb eines großen Wohnkomplexes. In diesem Fall ist der validationGranularity SUB_PREMISE, aber der geocodeGranularity ist PREMISE.
Weitere Informationen finden Sie im Referenzhandbuch unter Granularität.

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.

Weitere Informationen finden Sie im Referenzhandbuch unter Verdict (Ergebnis) und Address (Adresse) im Abschnitt addressComplete.

Adressqualität

Eine Reihe möglicher Felder weisen entweder auf Probleme mit Adresskomponenten oder auf Anpassungen daran 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
}
Weitere Informationen finden Sie im Referenzhandbuch unter Urteil.

Mögliche nächste Aktion

Das Ergebnisfeld possibleNextAction bietet eine interpretative Zusammenfassung der API-Antwort, die Ihnen bei der Entscheidung über eine mögliche nachfolgende Aktion helfen soll. 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 stellt die Formatierung für die verarbeitete Adresse bereit, 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.

Weitere Informationen finden Sie im Referenzhandbuch unter Address.

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 bereitgestellte Komponentenfeld anhand seines Namens, Typs und Konfidenzniveaus.

Weitere Informationen finden Sie im Referenzhandbuch unter addressComponent.

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.

Weitere Informationen finden Sie im Referenzhandbuch unter Geocode.

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.

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

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 Property 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.