Validierungslogik erstellen

In diesem Dokument wird ein Prozess zum Erstellen eines Adressprüfungssystems beschrieben, mit dem verschiedene Antworten der Address Validation API verarbeitet werden. Sie erfahren, wie Sie Ihre Logik so erstellen, dass die Antwort richtig verwendet wird, andere Signale aus der API untersucht werden und wann und wie Sie Ihre Kunden um weitere Informationen bitten können.

Im Allgemeinen wird durch die API-Antwort bestimmt, wie das System eine Adresse verarbeiten soll:

• handyman Problem beheben: Die Adresse hat eine geringe Qualität. Sie sollten nach weiteren Informationen fragen.
• edit Bestätigen: Die Adresse ist qualitativ hochwertig, aber die Eingabeadresse wurde geändert. Möglicherweise werden Sie zur Bestätigung aufgefordert.
• check Akzeptieren: Die Adresse hat eine hohe Qualität. Sie können die angegebene Adresse übernehmen.

Schlüsselzweck

Dieses Dokument hilft Ihnen dabei, Ihr System so anzupassen, dass die API-Antwort bestmöglich analysiert und die nächsten Aktionen anhand der angegebenen Adressen ermittelt 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. Du kannst auch die Open-Source-Implementierung dieser Logik in der erweiterten Komponentenbibliothek verwenden.

Workflowübersicht

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

1. Der zu verwendende Workflow (basierend auf dem Verhalten von Korrektur, Bestätigen und Akzeptieren).
2. Die ersten Signale in der Antwort, die geprüft werden sollen. Die hier beschriebenen Signale stammen aus dem Attribut verdict und sind nicht die einzigen Signale, die geprüft werden müssen. Sie bieten auch einen ersten Indikator für 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
handyman Adresse korrigieren	Die Antwort von verdict gibt wichtige fehlende Informationen an, die bereitgestellt werden sollten. Die von der Address Validation API zurückgegebene Adresse hat möglicherweise keine Zustellungsqualität. Workflow Prüfen Sie bei Bedarf die Adresskomponenten. Bitte den Kunden, Probleme mit der Adresse zu beheben. Fordern Sie eine Überprüfung der aktualisierten Adresse an. Optional: Senden Sie eine Anfrage an den Feedbackendpunkt für die API. Weitere Informationen Mit der Adresse fortfahren. Ergebnissignale Es gelten alle der folgenden Punkte: „validationGranularity“ ist auf „OTHER“ gesetzt. Siehe Detaillierungsgrad. addressComplete ist false.
edit Adresse bestätigen	Die Antwort von verdict gibt eine Lieferadresse an, es wurden jedoch Änderungen an der ursprünglichen Eingabe vorgenommen: Es werden Daten abgeleitet, die entweder korrigiert wurden oder Daten, die bestätigt werden können. Workflow Erforderliche Korrekturen: Prüfen Sie bei Bedarf die Adresskomponenten. Fordern Sie eine Überprüfung der aktualisierten Adresse an. Optional: Senden Sie eine Anfrage an den Feedbackendpunkt für die API. Weitere Informationen Mit der Adresse fortfahren. Keine Korrekturen erforderlich: Optional: Senden Sie eine Anfrage an den Feedbackendpunkt für die API. Weitere Informationen Mit der Adresse fortfahren. Ergebnissignale Alle der folgenden Bedingungen gelten: validationGranularity enthält mindestens ROUTE. Siehe Detaillierungsgrad. addressComplete ist true. Das Feld hasInferredComponents ist true ODER das Feld hasReplacedComponents ist true.
check Adresse akzeptieren	Die Antwort der Address Validation API gibt eine Adresse von hervorragender Qualität an. Workflow Mit zurückgegebener Adresse fortfahren. Ergebnissignale Alle der folgenden Bedingungen gelten: validationGranularity enthält mindestens PREMISE. Siehe Detaillierungsgrad. addressComplete ist true. Keine abgeleiteten oder ersetzten Komponenten.

Implementierungsleitfaden

Wenn Sie herausfinden möchten, wie Ihr System auf Signale der Address Validation API reagiert, können Ihnen die folgenden Empfehlungen dabei helfen, ein effektiveres Antwortmodell zu erstellen. Dies sind jedoch nur Empfehlungen. Denken Sie also daran, dass Ihre Implementierung zu Ihrem Geschäftsmodell passen sollte.

	Anleitung	Details
Risikostufe	Berücksichtigen Sie die Toleranz für Ihre Situation, wenn Sie ein Gleichgewicht zwischen der Aufforderung zu Korrekturen und der Annahme der eingegebenen Adresse finden.	Die Address Validation API gibt eine Vielzahl von Signalen zurück, die Sie in Ihre Risikostufe einbeziehen können, um Ihren Validierungsprozess zu optimieren. Wenn eine Adresse beispielsweise eine nicht bestätigte Hausnummer enthält, können Sie diese trotzdem akzeptieren. Wenn Ihr Geschäftsbetrieb jedoch eine höhere Adressgenauigkeit erfordert, könnten Sie den Nutzer dazu auffordern. Ein Beispiel, das in beide Kategorien fallen könnte, finden Sie unter Nicht in den USA unbestätigte Hausnummer unter Adresse akzeptieren – Beispiele.
Adressen akzeptieren	Wenn der Kunde nicht auf die Aufforderungen reagiert, empfiehlt es sich, dem System die Eingabe des ursprünglichen Eintrags zu erlauben.	In diesen Fällen hat der Kunde möglicherweise eine Adresse eingegeben, die nicht im System vorhanden ist, z. B. ein Neubau.
Feedback geben	Wenn Sie noch einmal eine Adressüberprüfung anfordern, können Sie auch eine Anfrage an den Endpunkt provideValidationFeedback senden.	So weiß Google, wie du die endgültige Antwort letztlich gehandhabt hast. Weitere Informationen

Adresse korrigieren

Korrigieren Sie eine Adresse, wenn aus den Ergebnissen deutlich hervorgeht, dass diese Adresse nicht zustellbar ist. Ihr System kann den Kunden dann auffordern, die erforderlichen Informationen anzugeben. Anschließend führen Sie den Workflow noch einmal aus, um eine Lieferadresse zu erhalten.

Signale korrigieren

Die Address Validation API liefert eine Reihe von Signalen, anhand derer Sie feststellen können, ob eine Adresse korrigiert werden sollte.

1. Detaillierungsgrad der Validierung und fehlende Komponenten

Die folgenden beiden Signale sind der beste Hinweis auf 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 das 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 weitere Signale zur Diagnose bestimmter Probleme bereit:

Verdächtige Komponenten	Wenn die Enum auf Bestätigungsebene für eine Komponente UNCOMFIRMED_AND_SUSPICIOUS lautet, 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, signalisieren, dass die Adresse nicht zustellbar ist und korrigiert werden muss. 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.

Beispiele für Adressen korrigieren

Adresse bestätigen

Sie bestätigen eine Adresse, wenn das Ergebnis anzeigt, dass die Address Validation API Adresskomponenten abgeleitet oder Änderungen vorgenommen hat, um eine validierte Adresse zu erstellen. In diesen Fällen haben Sie eine Lieferadresse, möchten aber mit größerer Sicherheit davon ausgehen, dass es sich um die vom Kunden gewünschte Adresse handelt.

Damit der Kunde die richtige Aufforderung erhält, würde 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. Siehe AddressComponent in der Referenz.

Signale bestätigen

Die Address Validation API liefert eine Reihe von Signalen, anhand derer Sie feststellen können, ob eine Adresse bestätigt werden sollte.

1. Validierungsgranularität

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

2. Sonstige Signale

Bei der Entscheidung, ob der Kunde die Adresseingabe bestätigt hat, liefert 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 ausgefüllt hat.
Ersetzte Daten	Wenn das Feld hasReplacedComponents den Wert true hat, wurden die eingegebenen Daten von der API durch Daten ersetzt, durch die die Adresse gültig ist.

3. US-Adresssignale

Bestimmte Felder, die nur für US-Adressen gelten, geben an, dass Ihre Logik Details mit 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.

Adressbeispiele bestätigen

Adresse akzeptieren

Sie akzeptieren eine Adresse, wenn das Ergebnis ein hohes Maß an Sicherheit gibt, 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, anhand derer Sie feststellen können, ob eine Adresse bestätigt werden sollte.

1. Validierungsgranularität

Ein validationGranularity von PREMISE oder höher ist akzeptabel, aber in einigen Fällen gibt ROUTE immer noch eine Lieferadresse an.

2. Sonstige Signale

Ein Ergebnis für eine qualitativ hochwertige Adresse sollte außerdem 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 Adressen in den USA gelten, geben eine Adresse von hoher Qualität 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