このドキュメントでは、Address Validation API からのさまざまなレスポンスを処理する住所確認システムを構築するプロセスについて説明します。このガイドでは、API レスポンスを解釈して、顧客に詳細情報を求めるタイミングと方法を判断する方法について説明します。
一般に、API レスポンスは、システムが住所を処理する方法を次のように決定します。
-
修正 - アドレスに重大な問題が含まれている可能性があります。
お客様に追加情報の提供を求めることを検討してください。 -
Add subpremises - 住所にサブプレミスが記載されていない可能性があります。
お客様に部屋番号の追加を促すことを検討してください。 -
確認 - 住所に軽微な問題が含まれている可能性があります。
お客様に住所が正しいことを確認していただくことを検討してください。 -
Accept（承認） - 住所に問題が含まれていない可能性があります。
自己責任で、プロンプトなしでアドレスを使用することを検討してください。
鍵の目的
このドキュメントは、API レスポンスを最適に分析し、指定された住所に対して行うべき次のアクションを決定するために、システムを変更するうえで役立ちます。次の疑似コードは、考えられるフローを示しています。
if (verdict.possibleNextAction == FIX)
Prompt the user to fix the address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
Prompt the user to add a unit number.
else if (verdict.possibleNextAction == CONFIRM)
Confirm with the user that the address is correct.
else
Continue with the address returned by the API.
具体的なロジックは状況によって異なります。詳しくは、検証ロジックをカスタマイズするをご覧ください。
ワークフローの例
次の表は、API レスポンスに基づいて顧客にプロンプトを表示するために実装できるワークフローの例をまとめたものです。
| システムの動作 | ||
|---|---|---|
| 住所を修正する |
|
|
| サブプレミスを追加 |
|
|
| 住所を確認する |
|
|
| アドレスを承認 |
|
|
検証ロジックをカスタマイズする
verdict.possibleNextAction フィールドの結果を使用して、システムが API レスポンスをどのように処理するかを決定できますが、ビジネス固有のニーズを処理するなど、カスタム ロジックの構築も検討できます。
このセクションの目的は、API レスポンスを解釈して、顧客にプロンプトを表示するかどうか、またどのように表示するかを判断するためのカスタム ロジックを開発する方法を示すことです。このセクションでは、カスタマイズで考慮すべきリスクレベルと追加の API レスポンス シグナルについて説明します。
ただし、verdict.possibleNextAction のみで次のステップを判断する場合でも、以下で説明する追加のシグナルは、アドレスに関する潜在的な問題の詳細を把握するのに役立ちます。
リスク許容度
Address Validation API からのシグナルに対するシステムの応答を設計する際は、次の推奨事項を参考にすると、より効果的な応答モデルを構築できます。ただし、これらはあくまで推奨事項です。実装はビジネスモデルに合わせて行う必要があります。
| ガイダンス | 詳細 | |
|---|---|---|
| リスクレベル |
修正を求めることと、入力された住所をそのまま受け入れることのバランスを取る際は、状況に応じた許容レベルを考慮してください。 |
Address Validation API は、リスクレベルに組み込んで検証プロセスを最適化できるさまざまなシグナルを返します。 たとえば、住所の番地が確認されていない場合でも、その住所を受け入れることができます。一方、ビジネス オペレーションでより正確な住所が必要な場合は、ユーザーに住所の入力を求めることができます。どちらのカテゴリにも該当する可能性がある例については、住所の承認 - 例の米国外の未確認の番地をご覧ください。 |
| アドレスを受け入れる |
お客様がプロンプトに応答しない場合は、システムが元のエントリを受け入れるようにすることをおすすめします。 |
このような場合、お客様がシステムに登録されていない住所（新築の住所など）を入力した可能性があります。 |
リスク回避型の購入手続きフローの例
配信失敗のリスクを軽減したい場合は、顧客へのプロンプトの頻度を増やすようにロジックをカスタマイズできます。たとえば、主な目的セクションで説明されているロジックを使用する代わりに、次のロジックを使用できます。
if (verdict.possibleNextAction == FIX or verdict.validationGranularity
== OTHER or verdict.validationGranularity == ROUTE)
Prompt customer to fix their address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
Prompt customer to add a unit number.
else if (verdict.possibleNextAction == CONFIRM or verdict.validationGranularity
== PREMISE_PROXIMITY or verdict.hasSpellCorrectedComponents or
verdict.hasReplacedComponents or verdict.hasInferredComponents)
Prompt customer to confirm their address.
else
Proceed with the returned address.
低摩擦の購入手続きフローの例
購入手続きフローでのユーザーの負担を軽減したい場合は、顧客へのプロンプトの表示頻度を減らすようにロジックをカスタマイズできます。たとえば、主な目的セクションで説明されているロジックを使用する代わりに、次のロジックを使用できます。
if (verdict.possibleNextAction == FIX)
Prompt customer to fix their address.
else if (verdict.hasReplacedComponents)
Prompt customer to confirm their address.
else
Proceed with the returned address.
FIX シグナル
結果から住所が配送できない可能性があることが明らかな場合は、住所を修正します。その後、システムからお客様に必要情報の提供を求めるメッセージが表示されます。お客様が情報を提供したら、ワークフローを再発行して配送先住所を取得します。
Address Validation API レスポンスの次のフィールドは、verdict.possibleNextAction に加えて、住所に重大な問題があるかどうか、またどのような問題があるかを判断するために使用できます。
| 検証の粒度 | 住所の検証粒度列挙型が OTHER の場合、住所が間違っている可能性があります。 |
|---|---|
| コンポーネントが見つからない | address.missingComponentTypes が空でない場合、住所に重要な情報が不足している可能性があります。 |
| 不審なコンポーネント | コンポーネントの確認レベルの列挙型が UNCONFIRMED_AND_SUSPICIOUS の場合、コンポーネントが正しくない可能性があります。 |
| 未解決のコンポーネント | unresolvedToken は、住所の有効な部分として認識されなかった入力の一部です。 |
| USPS DPV 確認 | uspsData.dpvConfirmation が N または空の場合、アドレスに問題がある可能性があります。このフィールドは、米国の住所でのみ使用できます。uspsData.dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。 |
CONFIRM_ADD_SUBPREMISES シグナル（米国の住所のみ）
Address Validation API のレスポンスで、住所に建物内の部屋番号が欠落している可能性があることが示された場合、お客様に住所を確認して部屋番号の追加を検討するよう促します。このような場合、建物の住所は有効である可能性が高いですが、結果として得られる住所がお客様の意図したものであることをより確信したい場合があります。
住所に建物名や部屋番号が欠落している可能性が高いかどうかを判断するために、verdict.possibleNextAction に加えて、Address Validation API レスポンスの次のフィールドを使用できます。
Missing subpremise component
|
address.missingComponentTypes フィールドに subpremise の値が含まれている場合、住所に部屋番号がないことを示します。 |
|---|---|
| USPS DPV 確認 | uspsData.dpvConfirmation が S の場合、住所のメインの番号が USPS データベース内の住所と一致したことを意味します。ただし、アドレスには二次番号も含まれていることが想定されていました。このフィールドは米国の住所でのみ使用できます。uspsData.dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。 |
CONFIRM シグナル
住所が確認されるのは、Address Validation API が検証済みの住所を生成するために住所の構成要素を推測または変更したことを判定が示している場合です。このような場合、配達可能な住所はありますが、結果として得られる住所がお客様の意図したものであるという確信を高めたいと考えています。
Address Validation API レスポンスの次のフィールドは、verdict.possibleNextAction に加えて、住所に軽微な問題があるかどうか、またどのような問題があるかを判断するために使用できます。
| 検証の粒度 | 住所の validationGranularity が ROUTE または PREMISE_PROXIMITY の場合、住所が間違っている可能性があります。 |
|---|---|
| 推論データ | hasInferredComponents フィールドが true の場合、API が他の住所コンポーネントから取得した情報を入力したことがわかります。 |
| 置き換えられたデータ | hasReplacedComponents フィールドが true の場合、API は入力されたデータを、住所を有効にするために必要と判断したデータに置き換えました。 |
| スペル修正 | hasSpellCorrectedComponents フィールドが true の場合、API は一部のスペルミスのあるコンポーネントのスペルを修正しました。 |
ACCEPT シグナル
Address Validation API の API レスポンスで、住所が配達可能であり、ダウンストリーム プロセスで顧客とのやり取りなしで使用できるという確信度が高い場合は、住所を受け入れることができます。
Address Validation API レスポンスの次のフィールドは、verdict.possibleNextAction に加えて、住所の品質が許容範囲内かどうかを判断するために使用できます。
| 検証の粒度 | PREMISE の validationGranularity は多くの場合許容されますが、ROUTE の値は配送可能な住所を示す場合があります。 |
|---|---|
| 推論されたデータはありません | hasInferredComponents フィールドが false の場合、出力で推論されたコンポーネントがないことを示します。 |
| 置き換えられたデータなし | hasReplacedComponents フィールドが false の場合、入力データが置き換えられていないことがわかります。 |
| スペル修正なし | hasSpellCorrectedComponents フィールドが false の場合、スペル修正が行われていないことがわかります。 |
| USPS DPV 確認 | uspsData.dpvConfirmation が Y の場合、住所が USPS データベースの住所と一致したことを意味します。このフィールドは、米国の住所でのみ使用できます。uspsData.dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。 |