このドキュメントでは、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.
具体的なロジックは状況によって異なります。詳しくは、実装ガイダンスをご覧ください。このロジックのオープンソース実装を使用することもできます。これは拡張コンポーネント ライブラリにあります。
ワークフローの概要
次の表に、システムに対する 2 つのアクションをまとめます。
- 修正、確認、承認の動作に基づく使用するワークフロー。
- レスポンスから確認する最初のシグナル。ここで説明するシグナルは
verdictプロパティから取得されるもので、確認すべき唯一のシグナルではありませんが、住所の品質を示す最初の指標となります。各動作タイプは、このドキュメントのセクションに対応しており、調査が必要になる可能性のある追加のシグナルについて説明しています。
| システムの動作 | |||
|---|---|---|---|
| 住所を修正する |
|
||
| 住所を確認する |
|
||
| 住所を承認する |
Address Validation API のレスポンスは、住所の品質が非常に高いことを示しています。
|
||
導入に関するアドバイス
Address Validation シグナルに対するシステムの応答を設計する際は、以下の推奨事項を参考にすると、より効果的な応答モデルを構築できます。ただし、これらはあくまで推奨事項であり、実装はビジネスモデルに適合させる必要があります。
| ガイダンス | 詳細 | |
|---|---|---|
| リスクレベル |
修正を求めることと、入力された住所を受け入れることのバランスを取る際には、状況に応じた許容レベルを考慮してください。 |
Address Validation API は、リスクレベルに組み込んで検証プロセスを最適化できるさまざまなシグナルを返します。 たとえば、住所の番地が未確認の場合でも、その住所を受け入れることができます。一方、ビジネス オペレーションでより正確な住所が必要な場合は、ユーザーにプロンプトを表示できます。どちらのカテゴリにも該当する可能性がある例については、住所の承認 - 例の米国以外の未確認の番地をご覧ください。 |
| アドレスを受け入れる |
お客様がプロンプトに応答しない場合は、システムが元のエントリを受け入れるようにすることをおすすめします。 |
このような場合、お客様は、新築など、システムに登録されていない住所を入力した可能性があります。 |
住所を修正
結果に住所が配送不可であることが明確に示されている場合は、住所を修正します。システムは、必要な情報の提供をお客様に求めることができます。その後、ワークフローを再発行して、配送可能な住所を取得します。
シグナルを修正する
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 が検証済みの住所を生成するために住所コンポーネントを推測または変更したことが示されている場合は、住所を確認します。このような場合、配送可能な住所はありますが、結果の住所がお客様の意図したものであることをより確実にする必要があります。
お客様に適切なプロンプトを提供するために、ロジックはサービスによってフラグが設定されたコンポーネントを識別し、API がコンポーネントに適用したアクションまたはフラグ（inferred、replaced、spellCorrected など）を特定します。リファレンスの AddressComponent をご覧ください。
シグナルを確認する
Address Validation API には、住所の確認が必要かどうかを判断するためのシグナルが多数用意されています。
1. 検証の粒度
ROUTE 以上の validationGranularity は許容されますが、PREMISE または SUBPREMISE のいずれかを使用すると、配信可能性のシグナルが強くなります。
2. その他のシグナル
お客様に住所の入力を確認することを決定する際、判定では、調査するコンポーネントを決定するために次の情報も提供されます。
| 推論データ |
hasInferredComponents フィールドが true の場合、API は他の住所コンポーネントから収集した情報を入力しています。 |
|---|---|
| 置換されたデータ |
hasReplacedComponents フィールドが true の場合、API は入力されたデータを、住所を有効にするために必要と判断したデータに置き換えました。 |
3. 米国の住所シグナル
米国の住所にのみ適用される特定のフィールドは、ロジックが顧客に詳細を確認する必要があることを示します。次のいずれかに該当する。
dpvConfirmation
|
S
|
|---|---|
| 住所に関する回答 | missingComponentTypes フィールドに subpremise の値が含まれています。
|
住所を承認する
判定により、住所が配送可能であり、下流プロセスで顧客とのやり取りなしで使用できるという高い信頼性が得られた場合、住所を受け入れます。
シグナルを受け入れる
Address Validation API には、住所の確認が必要かどうかを判断するためのシグナルが多数用意されています。
1. 検証の粒度
validationGranularity が PREMISE 以上であれば許容範囲内ですが、ROUTE でも配送可能な住所を示す場合があります。
2. その他のシグナル
高品質な住所の判定では、次の情報も提供されます。
- 置換されたデータがない。この例では
hasReplacedComponents: FALSEです。 - 推論されたコンポーネントがない。この例では
hasInferredComponents: FALSEです。
3. 米国の住所シグナル
米国の住所にのみ適用される特定のフィールドは、配送可能な高品質の住所を示します。有効な米国の住所の場合、次のように表示されます。
dpvConfirmation
|
Y
|
|---|