Validierungslogik erstellen

In diesem Dokument wird ein Prozess zum Erstellen eines Adressprüfungssystems beschrieben, mit dem verschiedene Antworten der Address Validation API verarbeitet werden können. 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 verarbeiten 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 eingegebenen Adresse 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 erfahren Sie, wie Sie Ihr System so anpassen, dass die API-Antwort optimal analysiert wird und Sie die nächsten Schritte für die bereitgestellten Adressen festlegen 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 der Property verdict und sind nicht die einzigen Signale, die geprüft werden sollten. Sie bieten jedoch 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 darauf hin, dass wichtige Informationen fehlen, die angegeben werden sollten. Die von der API zurückgegebene Adresse ist möglicherweise nicht zustellbar.

Workflow

  1. Untersuchen Sie bei Bedarf die Adresskomponenten.
  2. Fordere den Kunden auf, Adressprobleme zu beheben.
  3. Fordern Sie eine Überprüfung 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. Korrekturen erforderlich:
    1. Untersuchen Sie bei Bedarf die Adresskomponenten.
    2. Fordern Sie eine Überprüfung 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 reagieren soll, können Ihnen die folgenden Empfehlungen dabei helfen, ein effektiveres Antwortmodell zu erstellen. Dies sind jedoch nur Empfehlungen. Denkt daran, dass die Implementierung zu eurem 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 Ihre Geschäftstätigkeit jedoch eine höhere Adressgenauigkeit erfordert, können Sie den Nutzer auffordern, die Adresse zu korrigieren. 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 einzurichten, 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 das 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 Adressen in den USA verarbeiten.

Beispiele für die Korrektur von Adressen

Adresse bestätigen

Sie bestätigen eine Adresse, wenn das Ergebnis darauf hindeutet, 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, muss Ihre Logik die vom Dienst gekennzeichneten Komponenten identifizieren, 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 Ihnen mitteilen, ob eine Adresse bestätigt werden sollte.

1. Validierungsgranularität

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

2. Sonstige Signale

Wenn Sie die Adresseingabe mit dem Kunden bestätigen möchten, liefert das Ergebnis auch die folgenden Informationen, um zu bestimmen, welche Komponenten untersucht werden sollen:

Abgeleitete Daten Wenn das Feld hasInferredComponents den Wert true hat, wissen Sie, dass die API Informationen eingefügt hat, die sie aus anderen Adresskomponenten abgeleitet hat.
Ersetzte Daten Wenn das Feld hasReplacedComponents den Wert true hat, hat die API die eingegebenen Daten 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 Ihnen mitteilen, ob eine Adresse bestätigt werden sollte.

1. Validierungsgranularität

Ein validationGranularity-Wert von PREMISE oder besser ist akzeptabel, aber in einigen Fällen ist auch bei ROUTE eine Zustellung möglich.

2. Sonstige Signale

Ein Ergebnis für eine Adresse von 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