Grundlegende Antworten zur Adressvalidierung

Die Antwort der Address Validation API enthält die folgenden Eigenschaften der obersten 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

Die Eigenschaft verdict fasst die Ergebnisse der Adressvalidierung zusammen und sollte die erste Eigenschaft sein, die bei der Entwicklung der Logik zur Adressprüfung ausgewertet wird. Je nach Qualität der Ausgabeadresse kann die Property verschiedene Felder zurückgeben. Das folgende Beispiel zeigt die verdict-Eigenschaft einer Adresse mit guter Qualität, die die folgenden Felder für diese spezielle Anfrage zurückgibt:

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

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

Detaillierungsgrad der Adresse

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

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

• inputGranularity: Beschreibt die Detailebene, die aus der an die Address Validation in Maps JavaScript API gesendeten Adresse erfasst wird. Der Detaillierungsgrad der Adresse in der Anfrage beeinflusst den Detaillierungsgrad der Adresse in der Validierungsantwort. Eine Adresse mit einem inputGranularity unter PREMISE führt in der Regel nicht zu einem validationGranularity auf PREMISE-Ebene.
• validationGranularity: Die Granularitätsebene, bis zu der die Address Validation in Maps JavaScript API die Adresse vollständig validieren kann. In den meisten Fällen weist eine Granularität von PREMISE oder SUB_PREMISE auf eine Qualitätsadresse hin, die wahrscheinlich zustellbar ist.
• geocodeGranularity: Beschreibt die Detailebene des Geocodes, der der Adresse zugeordnet ist. So kann es beispielsweise sein, dass in den Google-Aufzeichnungen eine Wohnungsnummer angegeben ist, aber nicht der genaue Standort dieser Wohnung in einem großen Wohnkomplex. In diesem Fall ist die validationGranularity SUB_PREMISE, die geocodeGranularity jedoch PREMISE.

Vollständigkeit der Adresse

Das Ergebnis gibt die Eigenschaft addressComplete als Signal für eine hochwertige Adresse zurück. Das bedeutet, dass sie keine fehlenden, nicht aufgelösten oder unerwarteten Komponenten enthält:

"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 weist entweder auf Probleme mit Adresskomponenten oder auf Anpassungen an ihnen hin, z. B. abgeleitete oder fehlende Adresskomponenten. Die folgende verdict-Property 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
}

Mögliche nächste Aktion

Das Ergebnis-Feld possibleNextAction bietet eine interpretative Zusammenfassung der API-Antwort, die bei der Entscheidung über eine mögliche Folgemaßnahme helfen soll. Dieses Feld wird aus anderen Feldern in der API-Antwort abgeleitet und sollte nicht als Garantie für die Richtigkeit oder Zustellbarkeit der Adresse betrachtet werden.

Die Properties address und addressComponent

Das Attribut address enthält die Formatierung für die in der Anfrage angegebene verarbeitete Adresse sowie Zusammenfassungen der Adresse auf Komponentenebene, einschließlich falsch geschriebener Teile der Adresse, ersetzter falscher Teile und abgeleiteter fehlender Teile.

Die Eigenschaft addressComponent ist eine Unterkomponente von address, die eine detaillierte Liste der Elemente oder Komponenten der Adresse enthält, die von der Address Validation in Maps JavaScript API verarbeitet wurden. Die API identifiziert jedes Komponentenfeld anhand von Name, Typ und Bestätigungsstufe.

Das Attribut geocode

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

Das Attribut metadata

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

Das Attribut uspsData

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 ausschließlich auf diese Property verlassen, um Adressen zu validieren, sondern auch verdict und address prüfen.