Validierungslogik erstellen

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

Im Allgemeinen wird durch die API-Antwort festgelegt, wie Ihr System eine Adresse verarbeiten sollte:

• Problem beheben: Die Adresse hat eine niedrige Qualität. Sie sollten nach weiteren Informationen fragen.
• Bestätigen: Die Adresse ist hochwertig, hat sich aber gegenüber der eingegebenen Adresse geändert. Möglicherweise fordern Sie eine Bestätigung auf.
• Akzeptieren: Die Adresse ist hochwertig. Sie können die angegebene Adresse übernehmen.

Schlüsselzweck

In diesem Dokument wird beschrieben, wie Sie Ihr System so anpassen können, dass die API-Antwort am besten analysiert und die nächsten Aktionen mit den angegebenen Adressen ausgeführt 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 erweiterten Komponentenbibliothek befindet.

Workflowübersicht

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

1. Der zu verwendende Workflow – je nach Korrektur, Bestätigung, Akzeptieren des Verhaltens.
2. Die ersten Signale, die in der Antwort geprüft werden sollen. Die hier beschriebenen Signale stammen aus dem Attribut verdict und sind nicht die einzigen Signale, auf die geprüft werden muss, sondern sie sind ein erster Indikator für 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.

Das Verhalten Ihres Systems
Adresse korrigieren	Die Antwort von verdict weist auf wichtige fehlende Informationen hin, die angegeben werden sollten. Die von der Address Validation API zurückgegebene Adresse hat möglicherweise keine lieferbare Qualität. Workflow Prüfen Sie bei Bedarf Adresskomponenten. Bitte den Kunden, die Adressprobleme zu beheben. Fordern Sie die Bestätigung der aktualisierten Adresse an. (Optional) Senden Sie eine Anfrage an den Feedback-Endpunkt der API. Siehe Umgang mit aktualisierten Adressen. Fahren Sie mit der Adresse fort. Ergebnissignale Es gilt eines der folgenden Kriterien: „validationGranularity“ ist auf „OTHER“ gesetzt. Siehe Granularitätswerte. addressComplete ist false.
Adresse bestätigen	Die Antwort von verdict gibt eine Lieferadresse an, hat aber Ä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 Adresskomponenten. Fordern Sie die Bestätigung der aktualisierten 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 Feedback-Endpunkt der API. Siehe Umgang mit aktualisierten Adressen. Fahren Sie mit der Adresse fort. Ergebnissignale Es gelten alle folgenden Bedingungen: validationGranularity enthält ROUTE oder höher. Siehe Granularitätswerte. addressComplete ist true. Das Feld hasInferredComponents ist true ODER das Feld hasReplacedComponents ist true.
Adresse akzeptieren	Die Antwort der Address Validation API zeigt eine Adresse von hervorragender Qualität an. Workflow Mit der Rückgabeadresse fortfahren. Ergebnissignale Es gelten alle folgenden Bedingungen: validationGranularity enthält PREMISE oder höher. Siehe Granularitätswerte. 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. Dabei handelt es sich jedoch nur um Empfehlungen. Ihre Implementierung sollte sich daher an Ihr Geschäftsmodell anpassen.

	Anleitung	Details
Risikostufe	Berücksichtigen Sie die jeweilige Toleranz, wenn Sie zwischen der Aufforderung zur Korrektur und der Annahme der eingegebenen Adresse abwägen.	Die Address Validation API gibt eine Vielzahl von Signalen zurück, die Sie in Ihre Risikostufe einbeziehen können, um den Validierungsprozess zu optimieren. Wenn eine Adresse beispielsweise eine nicht bestätigte Hausnummer hat, können Sie diese trotzdem akzeptieren. Wenn Ihre Geschäftstätigkeit jedoch eine höhere Adressgenauigkeit erfordert, können Sie den Nutzer auffordern. Ein Beispiel für beide Kategorien finden Sie unter Nicht in den USA nicht bestätigte Hausnummer in Adresse akzeptieren – Beispiele.
Adressen akzeptieren	Es empfiehlt sich, Ihrem System zu erlauben, den ursprünglichen Eintrag zu akzeptieren, wenn der Kunde nicht auf Aufforderungen reagiert.	In diesen Fällen kann der Kunde eine Adresse eingegeben haben, die sich nicht im System befindet, 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 weiteren Verlauf dieses Dokuments wird eine Reihe von Beispielen verwendet, die Ihnen helfen, den oben beschriebenen Prozess für die Fehlerbehebung, Bestätigung und Annahme zu verstehen. 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 senden Sie Ihren Workflow noch einmal, 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, über die Sie informiert werden, ob eine Adresse korrigiert werden sollte.

1. Detaillierungsgrad der Validierung und fehlende Komponenten

Diese beiden Signale liefern den besten Hinweis auf eine problematische Adresse:

• Wenn das Feld validationGranularity auf OTHER gesetzt ist, sollte Ihr System Signale von Adresskomponenten untersuchen, um mehr darüber zu erfahren, wo der Fehler aufgetreten ist und wie er behoben werden kann.
• Immer wenn das nachverarbeitete address-Objekt ein missingComponentTypes-Feld zurückgibt, sollte Ihr System nach dieser Komponente suchen. Fehlende Komponenten führen außerdem dazu, dass eine Adresse unvollständig und nicht zustellbar ist.

2. Sonstige Signale

Die Address Validation API stellt auch die anderen Signale bereit, mit denen sich bestimmte Probleme diagnostizieren lassen:

Verdächtige Komponenten	Wenn die Aufzählung der Bestätigungsebene für eine 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. US-Adresssignale

Bestimmte Felder, die nur für US-Adressen gelten, sind ein nützliches Hinweis darauf, dass die Adresse nicht lieferbar ist und korrigiert werden sollte. Für eine Adresse, die korrigiert werden muss, sollte Folgendes angezeigt werden:

dpvConfirmation	Entweder N, D oder leer.

Weitere Informationen zu dpvConfirmation findest du unter Umgang mit Adressen in den USA.

Adressbeispiele korrigieren

Adresse bestätigen

Sie bestätigen eine Adresse, wenn das Ergebnis ergibt, dass die Address Validation API Adresskomponenten abgeleitet oder geändert hat, um eine validierte Adresse zu erzeugen. In diesen Fällen haben Sie eine Lieferadresse, sollten sich aber mit größerer Sicherheit darauf verlassen können, dass die resultierende Adresse vom Kunden beabsichtigt ist.

Damit der Kunde die richtigen Aufforderungen erhält, identifiziert Ihre Logik die vom Dienst gekennzeichneten Komponenten, um zu bestimmen, welche Aktion oder welches API-Flag 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 noch einmal Anfragen an die Address Validation API senden, können Sie außerdem provideValidationFeedback aufrufen, um das Ergebnis anzugeben. Siehe Umgang mit aktualisierten Adressen.

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 entweder PREMISE oder SUBPREMISE bieten ein stärkeres Signal für die Zustellbarkeit.

2. Sonstige Signale

Bei der Entscheidung, die Adresseingabe beim Kunden zu bestätigen, enthält das Ergebnis auch Folgendes, um zu bestimmen, welche Komponenten untersucht werden sollen:

Abgeleitete Daten	Wenn das Feld hasInferredComponents den Wert true hat, wissen Sie, dass die API Informationen aus anderen Adresskomponenten übernommen hat.
Ersetzte Daten	Wenn das Feld hasReplacedComponents den Wert true hat, ersetzt die API die eingegebenen Daten durch Daten, die als gültig erachtet wurden.

3. US-Adresssignale

Bestimmte Felder, die nur für Adressen in den USA gelten, geben an, dass Ihre Logik die Details gegenüber dem Kunden bestätigen soll. Es gibt folgende Möglichkeiten:

dpvConfirmation	S Weitere Informationen zu dpvConfirmation findest du unter Umgang mit Adressen in den USA.
Adressantwort	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 Ergebnis ein hohes Maß an Gewissheit bietet, dass die Adresse lieferbar ist und ohne weitere Kundeninteraktion im nachgelagerten Prozess verwendet werden kann.

Signale akzeptieren

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 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. US-Adresssignale

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

dpvConfirmation	Y Weitere Informationen zu dpvConfirmation findest du unter Umgang mit Adressen in den USA.

Adressbeispiele akzeptieren