Validierungsantwort verstehen

Die Address Validation API verwendet eine Adresse als Eingabe. Die API gibt dann eine Antwort zurück, die Folgendes enthält:

  • Das Ergebnis für die Validierung der gesamten Adresse und für die Validierung der einzelnen Adresskomponenten (Straßennummer, Straßenname, Stadt usw.).

  • Ein einzelner String mit der vollständigen, von der API festgelegten Adresse.

  • Einzelne Eigenschaften, die jede Komponente der Adresse gemäß API enthalten.

  • Eine Liste der fehlenden Adresskomponenten, aller nicht bestätigten Adresskomponenten und aller Adresskomponenten, die nicht aufgelöst werden konnten.

  • Die Geocodierung der Adresse.

  • Für die Regionen „US“ und „PR“ die USPS-Daten für die Adresse

Mit der API-Antwort können Sie dafür sorgen, dass die Adresse vorhanden ist und die für Ihre Anforderungen erforderliche Qualität hat. Wenn die Antwort der API angibt, dass eine Adresse unvollständig oder falsch ist, kannst du den Nutzer auffordern, die Adresse zu aktualisieren. Nachdem der Nutzer das Update abgeschlossen hat, verwenden Sie die API, um die aktualisierte Adresse zu validieren.

In diesem Dokument wird beschrieben, wie die API-Antwort verarbeitet und einige häufige Fehler in der von der API erkannten Eingabeadresse verarbeitet werden.

Hinweis:Einen besseren Überblick darüber, wie die API Fehler mit der Eingabeadresse verarbeitet, erhalten Sie in der Demoversion. In der Demo können Sie Adressen eingeben und die Antwort dann als visualisierten Inhalt und als JSON-Objekt ansehen.

Informationen zur Antwort

Das JSON-Objekt, das die Validierungsantwort darstellt, enthält zwei übergeordnete Attribute: result vom Typ ValidationResult und 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 wird die Interpretation des Attributs result beschrieben. Weitere Informationen zu responseID finden Sie unter Aktualisierte Adresse validieren und Feedback zur Adressüberprüfung geben.

Das Attribut „Ergebnis“

Das Attribut verdict in der Validierungsantwort gibt die Gesamtergebnisse der Validierung an. Das Attribut verdict enthält die folgenden Attribute:

  • inputGranularity

    Gibt den Detaillierungsgrad der Eingabeadresse an, der sich durch das Parsen der Adresse ergibt, aber nicht validiert wird. Diese Properties können zum Beispiel PREMISE für eine Adresse enthalten, die in das Ergebnis auf Gebäudeebene aufgelöst wird, BLOCK für eine Adresse, die in einen Block aufgelöst wird, oder ROUTE für eine Adresse, die einer Route zugeordnet wird, z. B. eine Straße, Straße oder Autobahn.

  • validationGranularity

    Gibt den Detaillierungsgrad an, mit dem die API die Adresse validieren kann. Dies ist der Detaillierungsgrad der validierten Adresse und nicht der Detaillierungsgrad der in address.formattedAddress oder address.postalAddress zurückgegebenen Adresse.

  • geocodeGranularity

    Gibt den Detaillierungsgrad des generierten Geocodes an.

  • addressComplete

    „true“, wenn die Adresse von der API als vollständig betrachtet wird. Das bedeutet, dass in der Eigenschaft address keine nicht aufgelösten Tokens (Adressstrings oder Symbole), unerwartete Adresskomponenten oder fehlende Adresskomponenten aufgeführt sind.

  • hasUnconfirmedComponents, hasInferredComponents, hasReplacedComponents

    Attribute, die angeben, ob mindestens eine Adresskomponente nicht kategorisiert oder validiert werden kann, ob mindestens eine Adresskomponente abgeleitet (hinzugefügt) wurde, die nicht in der Eingabe enthalten war, und ob mindestens eine Adresskomponente ersetzt wurde.

Ergebnis für eine vollständige Adresse mit abgeleiteten Komponenten

Im folgenden Beispiel sehen Sie das Attribut verdict für eine vollständige Adresse mit abgeleiteten Komponenten:

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

Der Detaillierungsgrad wird in eine Räumlichkeit aufgelöst und die Adresse ist vollständig, aber die API hat den Wert einiger Komponenten abgeleitet. In diesem Beispiel wurde in der Eingabeadresse die US-amerikanische Postleitzahl weggelassen, die die API vom Rest der Adresse ableiten konnte. Ein vollständigeres Beispiel finden Sie unter Abgeleitete Adresskomponenten.

Ergebnis für eine Adresse mit nicht bestätigten Komponenten

Obwohl eine Eingabeadresse als vollständig betrachtet werden kann, selbst wenn abgeleitete Komponenten vorhanden sind, kann eine Adresse nicht als vollständig betrachtet werden, wenn es unaufgelöste Adresstokens, unerwartete Adresskomponenten oder fehlende Adresskomponenten gibt.

Im nächsten Beispiel ist hasUnconfirmedComponents auf true gesetzt, um anzugeben, dass die Adresse mindestens eine Adresskomponente hat, die nicht kategorisiert oder validiert werden kann:

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

In diesem Fall wird der Detaillierungsgrad der validierten und geocodierten Adresse auf OTHER gesetzt und das Attribut addressComplete in der Antwort weggelassen, um anzugeben, dass die Adresse nicht vollständig ist. Ein vollständigeres Beispiel finden Sie unter Fehlende und nicht bestätigte Adresskomponenten.

Beispielantworten

In den folgenden Abschnitten finden Sie Antworten für verschiedene Szenarien, z. B. für eine vollständige Adresse und häufige Fehler bei der Validierung von Adressen. In diesen Beispielen gilt Folgendes:

  • Wenn die Antwort addressComplete auf true gesetzt hat, hat die API ermittelt, dass die Eingabeadresse von guter Qualität ist.

  • Wenn die Address Validation API angibt, dass sie wesentliche Änderungen an der Adresse vorgenommen hat oder dass die Adresse Fehler enthält, müssen Sie die zurückgegebene Adresse bei Ihrem Kunden bestätigen.

Vollständige, qualitativ hochwertige Adresse

Wenn die API ermittelt, dass eine Adresse vollständig ist, wird addressComplete im Attribut verdict der Antwort auf true gesetzt.

Beispiel:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

Das Attribut address der Antwort enthält alle von der API festgelegten Details der Adresse. Die Antwort enthält die Property formattedAddress, die die korrigierte und validierte Adresse als einzeiligen String enthält. Wir empfehlen, die einzeilige Adresse im Feld formattedAddress für die vollständige Adresse zu verwenden, da sie kleine Korrekturen und Ergänzungen enthalten kann, z. B. Großschreibung und ZIP+4 in den USA.

Das Attribut address gibt außerdem an, ob es Probleme gibt, die von der API für die einzelnen Adresskomponenten festgestellt werden. Für jede Komponente, z. B. den Straßennamen oder die Stadt, enthält das Feld address das Feld confirmationLevel. Zulässige Werte:

  • CONFIRMED gibt an, dass die API prüfen konnte, ob die Komponente vorhanden ist.
  • UNCONFIRMED_BUT_PLAUSIBLE gibt an, dass die Komponente nicht bestätigt werden konnte, aber verfügbar ist.
  • UNCONFIRMED_AND_SUSPICIOUS gibt an, dass die Komponente nicht bestätigt wurde und wahrscheinlich falsch ist.

Beispiel:

"address": {
  // Validated address as a single string.
  "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
  // Individual validated address components.
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043-1351",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  // Validation results for each component.
  "addressComponents": [
    {
      "componentName": {
        "text": "1600",
        "languageCode": "en"
      },
      "componentType": "street_number",
      "confirmationLevel": "CONFIRMED"
    },
    {
      "componentName": {
        "text": "Amphitheatre Pkwy",
        "languageCode": "en"
      },
      "componentType": "route",
      "confirmationLevel": "CONFIRMED"
    },
    …
  ]
  // List of any missing, unconfirmed, or unresolved address components.
  // These properties are omitted from the response if they are empty.
  "missingComponentTypes": [],
  "unconfirmedComponentTypes": [],
  "unresolvedTokens": []
}

Abgeleitete Adresskomponenten

Wenn die Eingabeadresse keine vollständige Adresse enthält, versucht die API, fehlende Adresskomponenten in die Antwort aufzunehmen. Diese hinzugefügten Komponenten werden als abgeleitete Adresskomponenten bezeichnet.

Sie verwenden beispielsweise die folgende Eingabeadresse:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

Diese Adresse enthält keine Postleitzahl in den USA. Die API kann die Postleitzahl anhand der restlichen Eingabeadresse ermitteln und zur Antwort hinzufügen.

In diesem Beispiel setzt die Property verdict den Wert hasInferredComponents auf true, um anzugeben, dass die API den Wert einer oder mehrerer Komponenten abgeleitet hat. Weil die Änderung jedoch geringfügig war, setzt die API addressComplete auf true. Das bedeutet, dass die Adresse immer noch von guter Qualität ist.

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

Für die abgeleitete Komponente setzt die API inferred im entsprechenden Element des addressComponents-Arrays des Attributs address auf true:

{
  "componentName": {
    "text": "94043"
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

Rechtschreibfehler in der Eingabeadresse

Häufig sind Rechtschreibfehler in einer Eingabeadresse, z. B. ein Tippfehler in der Stadt oder im Bundesland. Statt „Mountain View“ geben Sie beispielsweise „MontainView“ als Ortsteil einer Adresse ein:

{
  "address": {
    "regionCode" : "US",
    "locality" : "MontainView",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

In diesem Beispiel gibt das Attribut verdict an, dass es den Wert einer oder mehrerer Komponenten ableiten konnte. Außerdem wird addressComplete auf true gesetzt, um anzugeben, dass die Eingabeadresse von guter Qualität ist, da sie noch in die Lage ist, die Adresse aufzulösen:

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

Die API versucht, die Adresse in die richtige Schreibweise umzuwandeln. Das entsprechende Adresselement im addressComponents-Array der address-Property zeigt den korrigierten String in der text-Property an. Außerdem gibt es einen Rechtschreibfehler, indem spellCorrected auf true gesetzt wird:

{
    "componentName": {
        "text": "Mountain View",
        "languageCode": "en"
    },
    "componentType": "locality",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

Fehlende und nicht bestätigte Adresskomponenten

Dabei kann ein Teil der Eingabeadresse weggelassen werden. Im folgenden Beispiel gibt der Nutzer eine Hausnummer ein, keinen Straßennamen:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600"]
  }
}

In diesem Fall wird im Attribut addressComplete das Attribut weggelassen, da zu viele Informationen für die API vorhanden sind, um die Adresse aufzulösen. Die API setzt hasUnconfirmedComponents außerdem auf true, um anzugeben, dass die Adresse nicht bestätigte Komponenten hat:

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

Außerdem sind validationGranularity und geocodeGranularity auf OTHER gesetzt, da die API die Adresse nicht auflösen konnte.

Im Array addressComponents der Property address markiert die API die Hausnummer als UNCONFIRMED_BUT_PLAUSIBLE:

{
  "componentName": {
    "text": "1600",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

Schließlich füllt die API die Arrays missingComponentTypes und unconfirmedComponentTypes des Attributs address mit den Komponenten aus, die in der Eingabe fehlen und die nicht bestätigt werden konnten:

"missingComponentTypes": [
  "route",
  "postal_code"
],
"unconfirmedComponentTypes": [
  "street_number"
]

Verschiedene Detaillierungsgrade verstehen

Der Detaillierungsgrad in der Antwort gibt Aufschluss darüber, wie grob die API ist oder wie sie die Adresse interpretieren kann. Sie verwenden beispielsweise die folgende Eingabeadresse:

{
  "address": {
    "regionCode": "US",
    "locality": "Northampton",
    "addressLines": ["6 South Main Street APT 456"]
  }
}

In diesem Beispiel sucht die API die Hausnummer in der USPS-Datenbank, aber die Wohnungsnummer nicht. Außerdem kann die API keinen genauen Geocode für die Hausnummer „6“ finden, aber eine für „4“ und „8“. In diesem Fall gibt die API die folgende verdict zurück:

"verdict": {
    "inputGranularity": "SUB_PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE_PROXIMITY",
    "addressComplete": true,
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

In dieser Antwort gilt:

  • inputGranularity ist SUB_PREMISE, da die API die Eingabeadresse zur Wohnungsebene parsen kann. inputGranularity gilt nur für die APIs-Funktionalität zum Parsen der Eingabeadresse. Sie gilt nicht für die Validierung der Adresse.

  • validationGranularity ist PREMISE, da die API die Existenz von Hausnummer „6“ aber nicht „APT 456“ validieren kann. Obwohl die API „APT 456“ nicht validieren kann, ist sie trotzdem in den Ausgabefeldern formattedAddress und postalAddress enthalten.

  • geocodeGranularity ist PREMISE_PROXIMITY, weil die API den Geocoding-Standort nur interpolieren kann und nicht für die genaue Adresse der Eingabe, die gefunden wurde.

Von USPS künstlich erzeugte Adresse erkannt

Wenn der USPS eine künstlich erstellte Adresse angibt, enthält das Feld errorMessage der Property uspsData der Antwort eine Fehlermeldung. Beispiel:

"uspsData": {
    "errorMessage": "AMS API processing was terminated due to the detection of
    what is determined to be an artificially created address. No address beyond
    this point has been validated and/or processed. If you believe this address
    was identified in error, please contact your Vendor."
}

Das Senden künstlich erstellter Adressen an die API kann dazu führen, dass der Zugriff auf die USPS-Datenbank verloren geht. Bei Erhalt dieser Fehlermeldung sollten Sie die Quelle der Adresse untersuchen, um zu verhindern, dass künstliche Adressen an die API gesendet werden.

Diese Sicherheitsmaßnahme soll verhindern, dass eine Adressliste künstlich erstellt wird, indem erkannt wird, dass eine eingereichte Adresse künstlich konstruiert und nicht rechtmäßig erworben wurde. Das dürfte sehr selten vorkommen.