Validierungslogik erstellen

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

Im Allgemeinen gibt die API-Antwort an, wie Ihr System mit einer Adresse umgehen sollte:

• Korrigieren: Die Qualität der Adresse ist niedrig. Sie sollten um weitere Informationen bitten.
• Bestätigen: Die Adresse ist von hoher Qualität, weicht aber von der eingegebenen Adresse ab. Möglicherweise werden Sie um eine Bestätigung gebeten.
• 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 ändern, dass die API-Antwort am besten analysiert und die nächsten Aktionen 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 in der Implementierungsanleitung. 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 sich nach dem Verhalten „Fehler beheben“, „Bestätigen“ und „Akzeptieren“ richtet.
2. Die ersten Signale, die in der Antwort geprüft werden. Die hier beschriebenen Signale stammen aus der Property verdict und sind nicht die einzigen Signale, die geprüft werden sollten. Sie liefern jedoch einen ersten Hinweis auf die Qualität der Adresse. Jedem Verhaltenstyp entspricht ein Abschnitt in diesem Dokument, in dem weitere Signale beschrieben werden, die Sie möglicherweise ebenfalls untersuchen müssen.

Systemverhalten
Adresse korrigieren	In der Antwort der verdict werden wichtige fehlende Informationen angegeben, die angegeben werden sollten. Die von der Address Validation API zurückgegebene Adresse ist möglicherweise nicht zustellbar. Workflow Prüfen Sie bei Bedarf die Adresskomponenten. Bitten Sie den Kunden, die Adressprobleme zu beheben. Fordere eine Bestätigung für die aktualisierte Adresse an. Optional: Senden Sie eine Anfrage an den Feedbackendpunkt für die API. Weitere Informationen finden Sie unter Aktualisierte Adressen verarbeiten. Fahren Sie mit der Adresse fort. Signale für die Einstufung Eine der folgenden Aussagen trifft zu: „validationGranularity“ ist auf „OTHER“ gesetzt. Siehe Werte für die Detailebene. addressComplete ist false.
Adresse bestätigen	Die Antwort der verdict enthält eine zustellbare Adresse, aber es wurden Änderungen an der ursprünglichen Eingabe vorgenommen: Es werden Daten abgeleitet, die entweder korrigiert oder bestätigt werden können. Workflow Erforderliche Korrekturen: Prüfen Sie bei Bedarf die Adresskomponenten. Fordere eine Bestätigung für die aktualisierte Adresse an. Optional: Senden Sie eine Anfrage an den Feedbackendpunkt für die API. Weitere Informationen finden Sie unter Aktualisierte Adressen verarbeiten. Fahren Sie mit der Adresse fort. Keine Korrekturen erforderlich: Optional: Senden Sie eine Anfrage an den Feedbackendpunkt für die API. Weitere Informationen finden Sie unter Aktualisierte Adressen verarbeiten. Fahren Sie mit der Adresse fort. Signale für die Einstufung Alle der folgenden Bedingungen müssen erfüllt sein: validationGranularity enthält ROUTE oder höher. Siehe Werte für die Detailebene. addressComplete ist true. Das Feld hasInferredComponents ist true ODER das Feld hasReplacedComponents ist true.
Adresse akzeptieren	Die Antwort der Address Validation API gibt an, dass die Adresse eine hervorragende Qualität hat. Workflow Mit der Rücksendeadresse fortfahren Signale für die Einstufung Alle der folgenden Bedingungen müssen erfüllt sein: validationGranularity enthält PREMISE oder höher. Siehe Werte für die Detailebene. addressComplete ist true. Keine abgeleiteten oder ersetzten Komponenten.

Implementierungsleitfaden

Wenn Sie festlegen, wie Ihr System auf Signale von der Address Validation API reagiert, können Ihnen die folgenden Empfehlungen dabei helfen, ein effektiveres Antwortmodell zu erstellen. Dies sind jedoch nur Empfehlungen. Die Implementierung sollte Ihrem Geschäftsmodell entsprechen.

	Anleitung	Details
Risikostufe	Berücksichtigen Sie die Toleranzgrenze für Ihre Situation, wenn Sie abwägen, ob Sie eine Korrektur anfordern oder die Adresse so akzeptieren, wie sie eingegeben wurde.	Die Address Validation API gibt eine Vielzahl von Signalen zurück, die Sie in Ihr Risikoniveau einbinden können, um den Validierungsprozess zu optimieren. Wenn eine Adresse beispielsweise eine nicht bestätigte Hausnummer hat, können Sie sie trotzdem akzeptieren. Wenn für Ihr Unternehmen hingegen eine genauere Adresse erforderlich ist, können Sie den Nutzer dazu auffordern. Ein Beispiel, das in beide Kategorien fallen könnte, finden Sie unter Nicht in den USA bestätigte Hausnummer im Hilfeartikel Zulässige Adressen – Beispiele.
Adressen akzeptieren	Es empfiehlt sich, dass Ihr System den ursprünglichen Eintrag akzeptiert, wenn der Kunde nicht auf Prompts 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.
Feedback geben	Wenn Sie einen Antrag auf Adressbestätigung noch einmal stellen, können Sie auch eine Anfrage an den Endpunkt provideValidationFeedback senden.	So kann Google nachvollziehen, wie Sie mit der endgültigen Antwort umgegangen sind. Weitere Informationen finden Sie unter Aktualisierte Adressen verarbeiten.

Demo ausprobieren Im Rest dieses Dokuments werden anhand verschiedener Beispiele die oben beschriebenen Schritte „Problem beheben“, „Bestätigen“ und „Akzeptieren“ veranschaulicht. Sie können die Ergebnisse dieser Beispiele in der Demo der Address Validation API ansehen.

Adresse korrigieren

Korrigieren Sie eine Adresse, wenn die Ergebnisse eindeutig darauf hinweisen, dass die Zustellung nicht möglich ist. Ihr System kann den Kunden dann auffordern, die erforderlichen Informationen anzugeben. Anschließend können Sie Ihren Workflow noch einmal starten, um eine Lieferadresse zu erhalten.

Hinweis: Wenn Sie Anfragen an die Address Validation API für dieselbe Adresse wiederholen, können Sie provideValidationFeedback aufrufen, um das Ergebnis anzugeben. Weitere Informationen finden Sie unter Adressen in den USA verarbeiten.

Signale korrigieren

Die Address Validation API bietet eine Reihe von Signalen, die Ihnen mitteilen, ob eine Adresse korrigiert werden sollte.

1. Detaillierungsgrad der Validierung und fehlende Komponenten

Anhand dieser beiden Signale lässt sich am besten erkennen, ob eine Adresse problematisch ist:

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

2. Sonstige Signale

Die Address Validation API bietet auch andere Signale, die bei der Diagnose bestimmter Probleme helfen:

Verdächtige Komponenten	Wenn die Bestätigungsebene einer Komponente UNCOMFIRMED_AND_SUSPICIOUS ist, ist die Komponente wahrscheinlich falsch.
Ungelö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, geben ein nützliches Signal, 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 Urteil darauf hinweist, dass die Address Validation API entweder Adressenkomponenten abgeleitet oder geändert hat, um eine bestätigte Adresse zu erstellen. In diesen Fällen haben Sie zwar eine zustellbare Adresse, möchten aber sicher sein, dass es sich bei der resultierenden Adresse um die vom Kunden beabsichtigte Adresse handelt.

Damit dem Kunden die richtige Aufforderung angezeigt werden kann, identifiziert Ihre Logik die vom Dienst gekennzeichneten Komponenten, um zu ermitteln, welche Aktion oder Kennzeichnung die API auf die Komponente angewendet hat, z. B. inferred, replaced oder spellCorrected. Weitere Informationen finden Sie in der Referenz unter AddressComponent.

Hinweis: Berücksichtige dein Risikoniveau, wenn du entscheidest, ob du die Adresse mit dem Kunden bestätigen oder als gültig akzeptieren möchtest. Wenn Sie Anfragen an die Address Validation API noch einmal senden, können Sie provideValidationFeedback anrufen, um das Ergebnis anzugeben. Weitere Informationen finden Sie unter Aktualisierte Adressen verarbeiten.

Signale bestätigen

Die Address Validation API bietet eine Reihe von Signalen, die Ihnen mitteilen, ob eine Adresse bestätigt werden sollte.

1. Detaillierungsgrad der Validierung

Ein validationGranularity von ROUTE oder höher ist akzeptabel, aber PREMISE oder SUBPREMISE liefern ein stärkeres Signal für die Zustellbarkeit.

2. Sonstige Signale

Wenn Sie sich entscheiden, die Adresse mit dem Kunden zu bestätigen, enthält das Urteil auch die folgenden Informationen, um zu bestimmen, welche Komponenten untersucht werden müssen:

Abgeleitete Daten	Wenn das Feld hasInferredComponents den Wert true hat, wissen Sie, dass die API Informationen aus anderen Adresskomponenten eingefügt 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, geben an, dass Sie die Details mit dem Kunden bestätigen sollten. Eine der folgenden Aussagen trifft zu:

dpvConfirmation	S Weitere Informationen zu dpvConfirmation finden Sie unter Umgang mit Adressen in den USA.
Antwort auf Anfrage	Enthält das Feld missingComponentType mit dem Wert subpremise. Hinweis: Wenn das Feld andere Typen als subpremise enthält, fällt die Aktion in die Kategorie „Adresse korrigieren“. Eine vollständige Liste der Adresstypen finden Sie in der Geocoding-Dokumentation.

Adressbeispiele bestätigen

Adresse akzeptieren

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

Signale akzeptieren

Die Address Validation API bietet eine Reihe von Signalen, die Ihnen mitteilen, ob eine Adresse bestätigt werden sollte.

1. Detaillierungsgrad der Validierung

Ein validationGranularity von PREMISE oder höher ist akzeptabel. In einigen Fällen gibt ROUTE jedoch weiterhin eine zustellbare Adresse an.

2. Sonstige Signale

Ein Urteil 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, geben an, dass es sich um eine hochwertige Adresse handelt, an die geliefert werden kann. Bei einer zulässigen Adresse in den USA sollte Folgendes angezeigt werden:

dpvConfirmation	Y Weitere Informationen zu dpvConfirmation finden Sie unter Umgang mit Adressen in den USA.

Akzeptierte Adressbeispiele