Validierungslogik erstellen

In diesem Dokument wird beschrieben, wie Sie ein System zur Adressprüfung erstellen, das eine Vielzahl von Antworten der Address Validation API verarbeiten kann. Es wird beschrieben, wie Sie Ihre Logik so erstellen, dass die Antwort richtig verwendet wird, wie Sie andere Signale der API untersuchen und wann und wie Sie Ihre Kunden um weitere Informationen bitten.

Im Allgemeinen bestimmt die API-Antwort, wie Ihr System eine Adresse behandeln soll:

  • Korrigieren: Die Adresse ist von geringer Qualität. Sie sollten nach weiteren Informationen fragen.
  • Bestätigen: Die Adresse ist von hoher Qualität, weist aber Änderungen gegenüber der Eingabeadresse auf. Sie können eine Bestätigung anfordern.
  • Akzeptieren: Die Adresse ist von hoher Qualität. Sie können die angegebene Adresse akzeptieren.

Schlüsselzweck

In diesem Dokument wird beschrieben, wie Sie Ihr System so anpassen, dass die API-Antwort optimal analysiert und die nächsten Schritte für die angegebenen Adressen festgelegt werden können. Der folgende Pseudocode veranschaulicht einen möglichen Ablauf.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

Die genaue Logik hängt von Ihrer Situation ab. Weitere Informationen finden Sie im Implementierungsleitfaden. Sie können auch unsere Open-Source-Implementierung dieser Logik verwenden, die sich in der Extended Component Library befindet.

Workflowübersicht

In der folgenden Tabelle sind zwei Aktionen für Ihr System zusammengefasst:

  1. Der zu verwendende Workflow, der auf dem Verhalten „Korrigieren, bestätigen, akzeptieren“ basiert.
  2. Die ersten Signale, die in der Antwort geprüft werden sollen. Die hier beschriebenen Signale stammen aus dem Attribut verdict. Es sind nicht die einzigen Signale, die geprüft werden sollten, aber sie bieten einen ersten Hinweis auf die Adressqualität. Jeder Verhaltenstyp entspricht einem Abschnitt in diesem Dokument, in dem weitere Signale beschrieben werden, die Sie möglicherweise ebenfalls untersuchen müssen.
Systemverhalten
Adresse korrigieren

Die Antwort von verdict weist auf wichtige fehlende Informationen hin, die angegeben werden sollten. Die von der API zurückgegebene Adresse ist möglicherweise nicht von zustellbarer Qualität.

Workflow

  1. Untersuchen Sie bei Bedarf die Adresskomponenten.
  2. Fordere den Kunden auf, Adressprobleme zu beheben.
  3. Fordern Sie eine Validierung der aktualisierten Adresse an.
  4. Mit Adresse fortfahren.

Einstufungssignale

Eine der folgenden Bedingungen ist erfüllt:
Adresse bestätigen

Die Antwort von verdict gibt eine zustellbare Adresse an, es wurden jedoch Änderungen an der ursprünglichen Eingabe vorgenommen: Es wurden Daten abgeleitet, die entweder korrigiert wurden oder bestätigt werden können.

Workflow

  1. Erforderliche Korrekturen:
    1. Untersuchen Sie bei Bedarf die Adresskomponenten.
    2. Fordern Sie eine Validierung der aktualisierten Adresse an.
    3. Mit Adresse fortfahren.
  2. Keine Korrekturen erforderlich:
  3. Mit Adresse fortfahren.

Einstufungssignale

Alle der folgenden Bedingungen sind erfüllt:
Adresse akzeptieren

Die Antwort der Address Validation API weist auf eine Adresse von hervorragender Qualität hin.

Workflow

Mit der zurückgegebenen Adresse fortfahren.

Einstufungssignale

Alle der folgenden Bedingungen sind erfüllt:

Implementierungsleitfaden

Wenn Sie festlegen, wie Ihr System auf Signale der Adressvalidierung reagiert, können die folgenden Empfehlungen Ihnen helfen, ein effektiveres Antwortmodell zu erstellen. Dies sind jedoch nur Empfehlungen. Denke daran, dass die Implementierung zu deinem Geschäftsmodell passen sollte.

Anleitung Details
Risikostufe

Berücksichtigen Sie bei der Abwägung zwischen der Aufforderung zu Korrekturen und der Akzeptanz der eingegebenen Adresse die Toleranzstufe für Ihre Situation.

Die Address Validation API gibt eine Vielzahl von Signalen zurück, die Sie mit Ihrem Risikoniveau kombinieren können, um Ihren Validierungsprozess zu optimieren.

Wenn eine Adresse beispielsweise eine unbestätigte Hausnummer hat, können Sie sie trotzdem akzeptieren. Wenn für Ihre Geschäftstätigkeit jedoch eine höhere Adressgenauigkeit erforderlich ist, können Sie den Nutzer auffordern, die Adresse einzugeben. Ein Beispiel, das in beide Kategorien fallen könnte, finden Sie unter Nicht bestätigte Hausnummer außerhalb der USA in Adresse akzeptieren – Beispiele.
Adressen akzeptieren

Es empfiehlt sich, Ihr System so zu konfigurieren, dass es die ursprüngliche Eingabe akzeptiert, wenn der Kunde nicht auf Aufforderungen reagiert.

In diesen Fällen hat der Kunde möglicherweise eine Adresse eingegeben, die nicht im System vorhanden ist, z. B. für einen Neubau.

Adresse korrigieren

Korrigieren Sie eine Adresse, wenn die Ergebnisse eindeutig darauf hinweisen, dass die Adresse nicht zustellbar ist. Ihr System kann den Kunden dann auffordern, die erforderlichen Informationen anzugeben. Anschließend können Sie den Workflow noch einmal ausführen, um eine zustellbare Adresse zu erhalten.

Signale korrigieren

Die Address Validation API liefert eine Reihe von Signalen, die darauf hinweisen, ob eine Adresse korrigiert werden sollte.

1. Validierungsgranularität und fehlende Komponenten

Diese beiden Signale sind die besten Indikatoren für eine problematische Adresse:

  • Wenn das Feld validationGranularity den Wert OTHER hat, sollte Ihr System die Signale der Adresskomponenten untersuchen, um mehr darüber zu erfahren, wo der Fehler aufgetreten ist und wie er behoben werden kann.
  • Wenn das nachbearbeitete address-Objekt ein missingComponentTypes-Feld zurückgibt, sollte Ihr System nach dieser Komponente suchen. Fehlende Komponenten machen eine Adresse ebenfalls unvollständig und unzustellbar.

2. Sonstige Signale

Die Address Validation API bietet auch andere Signale, mit denen sich bestimmte Probleme diagnostizieren lassen:

Verdächtige Komponenten Wenn die Enum für die Bestätigungsstufe einer Komponente UNCOMFIRMED_AND_SUSPICIOUS ist, ist die Komponente wahrscheinlich falsch.
Nicht aufgelöste Komponente Ein unresolvedToken ist ein Teil der Eingabe, der nicht als gültiger Teil einer Adresse erkannt wird.

3. Signale für US-Adressen

Bestimmte Felder, die nur für US-Adressen gelten, sind ein nützliches Signal dafür, dass die Adresse nicht zustellbar ist und korrigiert werden sollte. Bei einer Adresse, die korrigiert werden muss, sollte Folgendes angezeigt werden:

dpvConfirmation Entweder N, D oder leer.

Weitere Informationen zu dpvConfirmation finden Sie unter US-Adressen verarbeiten.

Beispiele für die Korrektur von Adressen

Adresse bestätigen

Sie bestätigen eine Adresse, wenn das Ergebnis darauf hinweist, dass die Address Validation API entweder Änderungen an Adresskomponenten abgeleitet oder vorgenommen hat, um eine validierte Adresse zu erstellen. In diesen Fällen haben Sie eine zustellbare Adresse, möchten aber sichergehen, dass die resultierende Adresse die vom Kunden beabsichtigte ist.

Damit der Kunde die richtige Aufforderung erhält, identifiziert Ihre Logik die vom Dienst gekennzeichneten Komponenten, um zu bestimmen, welche Aktion oder welches Flag die API auf die Komponente angewendet hat, z. B. inferred, replaced oder spellCorrected. Weitere Informationen finden Sie in der Referenz unter AddressComponent.

Signale bestätigen

Die Address Validation API liefert eine Reihe von Signalen, die Aufschluss darüber geben, ob eine Adresse bestätigt werden sollte.

1. Validierungsgranularität

Ein validationGranularity-Wert von ROUTE oder besser ist akzeptabel, aber entweder PREMISE oder SUBPREMISE liefert ein stärkeres Signal für die Zustellbarkeit.

2. Sonstige Signale

Wenn Sie sich entscheiden, die Adresseingabe mit dem Kunden zu bestätigen, liefert das Ergebnis auch Folgendes, um zu bestimmen, welche Komponenten untersucht werden sollen:

Abgeleitete Daten Wenn das Feld hasInferredComponents den Wert true hat, hat die API Informationen eingefügt, die sie aus anderen Adresskomponenten abgeleitet hat.
Ersetzte Daten Wenn das Feld hasReplacedComponents den Wert true hat, wurden die eingegebenen Daten durch die API durch Daten ersetzt, die die Adresse gültig machen.

3. Signale für US-Adressen

Bestimmte Felder, die nur für US-Adressen gelten, weisen darauf hin, dass Ihre Logik Details mit dem Kunden bestätigen sollte. Eine der folgenden Bedingungen ist erfüllt:

dpvConfirmation S

Weitere Informationen zu dpvConfirmation finden Sie unter US-Adressen verarbeiten.
Adressantwort Enthält das Feld missingComponentTypes mit dem Wert subpremise.

Beispiele für die Bestätigung der Adresse

Adresse akzeptieren

Sie akzeptieren eine Adresse, wenn das Ergebnis mit hoher Wahrscheinlichkeit darauf hindeutet, dass die Adresse zustellbar ist und ohne weitere Kundeninteraktion im nachgelagerten Prozess verwendet werden kann.

Signale akzeptieren

Die Address Validation API liefert eine Reihe von Signalen, die Aufschluss darüber geben, ob eine Adresse bestätigt werden sollte.

1. Validierungsgranularität

Ein validationGranularity-Wert von PREMISE oder besser ist akzeptabel, aber in einigen Fällen weist ROUTE immer noch auf eine zustellbare Adresse hin.

2. Sonstige Signale

Ein Ergebnis für eine Adresse mit hoher Qualität sollte außerdem Folgendes enthalten:

  • Keine ersetzten Daten: In diesem Fall hasReplacedComponents: FALSE.
  • Keine abgeleiteten Komponenten. In diesem Fall hasInferredComponents: FALSE.

3. Signale für US-Adressen

Bestimmte Felder, die nur für US-Adressen gelten, weisen auf eine hochwertige Adresse hin, an die zugestellt werden kann. Für eine zulässige US-Adresse sollte Folgendes angezeigt werden:

dpvConfirmation Y

Weitere Informationen zu dpvConfirmation finden Sie unter US-Adressen verarbeiten.

Beispiele für akzeptierte Adressen