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:

• Problem beheben: Die Adresse hat eine niedrige Qualität. 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. 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	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 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 Granularitätswerte. addressComplete ist false.
Adresse bestätigen	Die Antwort von verdict gibt eine Lieferadresse an, hat jedoch Änderungen an der ursprünglichen Eingabe vorgenommen: Es wurden 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 Feedback-Endpunkt der API. Siehe Umgang mit aktualisierten Adressen. Fahren Sie mit der Adresse fort. Es sind 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 Es gelten alle folgenden Bedingungen: 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 Sie mithilfe der folgenden Empfehlungen ein effektiveres Antwortmodell 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 auffordern oder die Adresse so akzeptieren sollen, 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 Ihre Geschäftstätigkeit jedoch eine höhere Adressgenauigkeit erfordert, können Sie den Nutzer 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 eine Anfrage zur Adressüberprüfung noch einmal senden, können Sie auch eine Anfrage an den Endpunkt provideValidationFeedback senden.	So erfährt Google, wie Sie mit der endgültigen Antwort umgegangen sind. Siehe Umgang mit aktualisierten Adressen.

Demo ausprobieren Im Rest dieses Dokuments werden verschiedene Beispiele verwendet, um Ihnen den oben beschriebenen Ablauf zu zeigen, wie Sie Fehler beheben, bestätigen und akzeptieren. Sie können sich die Ergebnisse dieser Beispiele ansehen, indem Sie sie in die Demo der Address Validation API eingeben.

Adresse korrigieren

Korrigieren Sie eine Adresse, wenn aus den Ergebnissen klar hervorgeht, dass die Adresse nicht zustellbar 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. Siehe Umgang mit US-Adressen.

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 die anderen Signale, mit denen sich bestimmte Probleme diagnostizieren lassen:

Verdächtige Komponenten	Wenn die Bestätigungsebene für eine 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, sehen Sie Folgendes:

dpvConfirmation	Entweder N, D oder leer.

Weitere Informationen zu dpvConfirmation finden Sie unter USA-Adressen 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 der Kunde die richtige Aufforderung erhält, 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ücksichtigen Sie Ihr Risikoniveau, wenn Sie entscheiden, ob Sie die Adresse beim Kunden bestätigen oder als gültig akzeptieren möchten. 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, anhand derer du feststellen kannst, 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 deine Logik die Details mit dem Kunden bestätigen sollte. Eine der folgenden Aussagen trifft zu:

dpvConfirmation	S Weitere Informationen zu dpvConfirmation findest du 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 zulässig. In einigen Fällen gibt ROUTE aber trotzdem eine Lieferadresse an.

2. Sonstige Signale

Ein Ergebnis für eine qualitativ hochwertige Adresse sollte auch 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 findest du unter Umgang mit Adressen in den USA.

Akzeptierte Adressbeispiele