このドキュメントでは、Address Validation API からのさまざまなレスポンスを処理する住所チェック システムを構築するプロセスについて説明します。レスポンスを正しく使用するためのロジックの構築方法、API からの他のシグナルの調査方法、顧客に詳細情報を求めるタイミングと方法についても説明します。
一般に、API レスポンスでは、システムが住所をどのように処理するかを次のように決定します。
- 修正 - 住所が低品質です。 詳細情報の入力を求められます。
- 確認 - 住所は高品質ですが、入力された住所と異なっています。確認を求めるメッセージが表示されることがあります。
- 承認 - 高画質の住所です。指定されたアドレスを受け入れることができます。
鍵の目的
このドキュメントは、API レスポンスを適切に分析し、指定された住所に対して次に取るべきアクションを決定するようにシステムを変更する際に役立ちます。次の擬似コードは、考えられるフローを示しています。
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.
正確なロジックは状況によって異なります。詳しくは、実装のガイダンスをご覧ください。このロジックのオープンソース実装を使用することもできます（Extended Component Library にあります）。
ワークフローの概要
次の表に、システムに対する 2 つのアクションの概要を示します。
- 使用するワークフローは、修正、確認、承認の動作に基づいています。
- レスポンスの確認する最初のシグナル。ここで説明するシグナルは
verdictプロパティから取得され、チェックする唯一のシグナルではなく、アドレス品質の初期指標を提供します。各動作タイプは、調査が必要なその他のシグナルについて説明したこのドキュメントのセクションに対応しています。
| システムの動作 | |||
|---|---|---|---|
| 住所を修正する |
|
||
| 住所を確認する |
|
||
| 住所を受け入れる |
Address Validation API のレスポンスは、住所の品質が優れていることを示しています。
|
||
導入に関するアドバイス
Address Validation API からのシグナルにシステムが応答する方法を設計する際は、次の推奨事項に従うことで、より効果的なレスポンス モデルを構築できます。ただし、これらはあくまでも推奨事項です。ビジネスモデルに適した実装にしてください。
| ガイダンス | 詳細 | |
|---|---|---|
| リスクレベル |
住所の修正を求めることと、入力された住所を受け入れることとの間でバランスを取る場合は、実際の状況に対する許容度を考慮してください。 |
Address Validation API はさまざまなシグナルを返します。これらのシグナルをリスクレベルに組み込んで検証プロセスを最適化できます。 たとえば、住所の番地が未確認の場合でも、その住所を使用できます。一方、ビジネス運営で住所の精度を高める必要がある場合は、ユーザーにメッセージを表示できます。いずれかのカテゴリに該当する例については、住所の受け入れ - 例の米国以外の未確認の番地をご覧ください。 |
| 住所を許可 |
お客様がプロンプトに応答しない場合は、システムで元のエントリを受け入れるようにすることをおすすめします。 |
この場合、新築など、お客様がシステムにない住所を入力した可能性があります。 |
| フィードバックを送信 |
住所検証リクエストを再発行するときに、 |
これにより、最終回答に最終的にどう対処したかを Google に知らせることができます。 住所の更新を処理するをご覧ください。 |
住所を修正
結果から住所を配送できないことが明らかな場合は、住所を修正します。システムは、お客様に必要な情報を提供するように促します。その後、配達可能な住所を取得するためにワークフローを再発行します。
シグナルを修正
Address Validation API には、住所を修正する必要があるかどうかを通知するさまざまなシグナルが用意されています。
1. 検証の粒度と欠落しているコンポーネント
次の 2 つのシグナルから、問題のある住所を最もよく把握できます。
validationGranularityフィールドがOTHERの場合、システムは住所コンポーネントのシグナルを調査して、エラーの発生場所とその修正方法を詳しく調べる必要があります。- 後処理された
addressオブジェクトがmissingComponentTypesフィールドを返すたびに、システムはそのコンポーネントをチェックする必要があります。コンポーネントがないと、住所が不完全で配達不能になります。
2. その他のシグナル
Address Validation API は、特定の問題の診断に役立つその他のシグナルも提供します。
| 不審なコンポーネント | コンポーネントの確認レベルの列挙型が UNCOMFIRMED_AND_SUSPICIOUS の場合、コンポーネントが正しくない可能性があります。
|
|---|---|
| 未解決のコンポーネント | unresolvedToken が入力の一部で、住所の有効な部分として認識されません。 |
3. 米国の住所シグナル
米国の住所にのみ適用される一部のフィールドは、住所が配送できないため修正する必要があることを示す有用なシグナルとなります。修正が必要な住所の場合は、次のように表示されます。
dpvConfirmation
|
N、D、空のいずれか。 |
|---|
dpvConfirmation について詳しくは、米国の住所を処理するをご覧ください。
住所の確認
Address Validation API が検証済みの住所を生成するために住所の構成要素を推測したか、住所の要素を変更したと判定された場合、その住所を確認します。このようなケースでは、配達可能な住所はありますが、結果として得られる住所がお客様が意図した住所であるという確信が持てるようになります。
ユーザーに正しいプロンプトを提供するため、ロジックはサービスによってフラグが付けられたコンポーネントを識別し、そのコンポーネント（inferred、replaced、spellCorrected など）に適用される API のアクションまたはフラグを決定します。リファレンスの AddressComponent をご覧ください。
シグナルを確認する
Address Validation API には、住所の確認が必要かどうかを通知するさまざまなシグナルが用意されています。
1. 検証の粒度
ROUTE 以上の validationGranularity は許容されますが、PREMISE または SUBPREMISE の方が配信可能であることを示す強いシグナルになります。
2. その他のシグナル
お客様と住所の入力を確認する際、判定結果では、調査すべき項目を判断するための以下の情報も提供されます。
| 推定データ | hasInferredComponents フィールドが true の場合、他の住所コンポーネントから取得した情報が API によって入力されたことがわかります。 |
|---|---|
| 置換されたデータ | hasReplacedComponents フィールドが true の場合、API は入力されたデータを、住所が有効とみなされるデータに置き換えました。 |
3. 米国の住所シグナル
米国の住所にのみ適用される一部のフィールドは、ロジックでお客様に詳細を確認する必要があることを示します。次のいずれかに該当します。
dpvConfirmation
|
S
|
|---|---|
| Address response（住所応答） | subpremise の値を持つ missingComponentType フィールドが含まれます。 |
住所を入力
判定の結果、住所が配送可能であり、ダウンストリーム プロセスでお客様がこれ以上操作しなくても使用できることが確実である場合、住所を受け入れます。
シグナルを受け入れる
Address Validation API には、住所の確認が必要かどうかを通知するさまざまなシグナルが用意されています。
1. 検証の粒度
PREMISE 以上の validationGranularity は許容されますが、場合によっては ROUTE が配達可能な住所を示すこともあります。
2. その他のシグナル
高品質なアドレスの判定結果は、次の情報も提供する必要があります。
- 置換されたデータがない。この場合は
hasReplacedComponents: FALSEです。 - 推定されるコンポーネントがない。この場合は
hasInferredComponents: FALSEです。
3. 米国の住所シグナル
米国の住所にのみ適用される一部のフィールドは、質の高い住所に配送できることを示しています。米国の住所が使用可能な場合は、次のように表示されます。
dpvConfirmation
|
Y
|
|---|