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"
}

Die verdict-Property

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. Im Folgenden sehen Sie beispielsweise das Attribut verdict einer Adresse mit guter Qualität, das 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 werden alle Felder der Property verdict zusammengefasst.

Detaillierungsgrad der Adresse

Der Adressdetaillierungsgrad bezieht sich auf die Detailebene, die verwendet wird, um die Spezifität einer Adresse oder eines Geocodes zu bestimmen. 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 wurde. Die Detailgenauigkeit der Adresse in der Anfrage beeinflusst die Detailgenauigkeit der Adresse in der Validierungsantwort. Eine Adresse mit einem inputGranularity unter PREMISE führt in der Regel nicht zu einer 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 hochwertige Adresse hin, die wahrscheinlich zustellbar ist.
• geocodeGranularity: Beschreibt die Detailgenauigkeit 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 das Attribut addressComplete als Signal für eine hochwertige Adresse zurück. Das bedeutet, dass keine Komponenten fehlen, nicht aufgelöst oder unerwartet 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 weist entweder auf Probleme mit Adresskomponenten oder auf Anpassungen an ihnen hin, 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
}

Mögliche nächste Schritte

Das Feld possibleNextAction enthält eine zusammenfassende Interpretation 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 seines Namens, Typs und Bestätigungsgrads.

Die geocode-Property

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

Die metadata-Property

Dieses Attribut wird möglicherweise nicht für jede Adresse ausgefüllt, die von der Address Validation in der Maps JavaScript API verarbeitet wird. Es gibt jedoch an, ob die Adresse vom Typ „Wohnadresse“, „Geschäftsadresse“ oder „Postfach“ ist.

Die uspsData-Property

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.