検証ロジックを作成する

このドキュメントでは、Address Validation API からのさまざまなレスポンスを処理するアドレスチェック システムを構築するプロセスについて説明します。お客様に詳細情報を尋ねるタイミングと方法を判断するために、API レスポンスの解釈方法について説明します。

一般に、API レスポンスから、システムが住所を処理する方法が決まります。

• 修正 - 住所に重大な問題が含まれている可能性があります。
  お客様に詳細情報を尋ねることを検討してください。
• サブプレミスを追加 - 住所にサブプレミスが含まれていない可能性があります。
  ユニット番号を追加するようお客様に求めるメッセージを表示することを検討してください。
• 確認 - 住所に軽微な問題が含まれている可能性があります。
  住所が正しいことを確認するようお客様に依頼することを検討してください。
• [承認] - 住所に問題がない場合。
  ご自身の責任で、プロンプトを表示せずに住所を使用することをご検討ください。

鍵の目的

このドキュメントは、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 からのレスポンスは、住所に重大な問題がある可能性があることを示します。たとえば、verdict.possibleNextAction は FIX です。お客様に詳細情報の提供を依頼することを検討してください。 ワークフロー 必要に応じて住所のコンポーネントを調査します。 住所に関する問題を解決するようお客様に伝えます。 更新された住所の確認をリクエストします。 （省略可）API のフィードバック エンドポイントにリクエストを送信します。住所の更新に対応するをご覧ください。 住所の入力に進みます。
サブプレミスを追加	verdict からのレスポンスは、住所にサブプレミスがない可能性があることを示しています。たとえば、verdict.possibleNextAction は CONFIRM_ADD_SUBPREMISES です。ユニット番号を追加するようお客様に依頼することを検討してください。 ワークフロー ユニット番号を追加するようお客様に伝えます。 更新された住所の確認をリクエストします。 （省略可）API のフィードバック エンドポイントにリクエストを送信します。住所の更新に対応するをご覧ください。 住所の入力に進みます。
住所を確認する	verdict からのレスポンスは、住所に軽微な問題がある可能性があることを示します。たとえば、verdict.possibleNextAction は CONFIRM です。住所を確認するようお客様に伝えることを検討してください。 ワークフロー 修正が必要な点: 必要に応じて住所のコンポーネントを調査します。 更新された住所の確認をリクエストします。 （省略可）API のフィードバック エンドポイントにリクエストを送信します。住所の更新に対応するをご覧ください。 住所の入力に進みます。 修正不要: （省略可）API のフィードバック エンドポイントにリクエストを送信します。住所の更新に対応するをご覧ください。 住所の入力に進みます。
住所を承認する	verdict からのレスポンスは、住所に問題がないことを示しています。たとえば、verdict.possibleNextAction は ACCEPT です。リスクレベルの場合と同様に、住所の確認を進めることを検討してください。 ワークフロー 返品先住所の手続きに進みます。

注: 同じ住所に対して Address Validation API へのリクエストを繰り返す場合は、provideValidationFeedback を呼び出して結果を示すことができます。住所の更新に対応するをご覧ください。

デモをお試しください。 このドキュメントの残りの部分では、さまざまな例を使用して、上記の修正、確認、承認のフロー プロセスについて説明します。これらの例の結果を確認するには、Address Validation 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 シグナル

住所が配送できない可能性があることが結果から明確にわかる場合は、住所を修正します。システムは、必要な情報を提供するようお客様にプロンプトを表示できます。その後、ワークフローを再発行して配送先住所を取得します。

verdict.possibleNextAction に加えて、Address Validation API レスポンスの次のフィールドを使用して、住所に重大な問題があるかどうか、問題の内容を判断できます。

検証の粒度	住所の検証の粒度列挙型が OTHER の場合、住所が正しくない可能性があります。
コンポーネントがない	address.missingComponentTypes が空でない場合、住所に重要な情報が不足している可能性があります。
不審なコンポーネント	コンポーネントの確認レベルの列挙型が UNCONFIRMED_AND_SUSPICIOUS の場合、コンポーネントが正しくありません。
未解決のコンポーネント	unresolvedToken は、住所の有効な部分として認識されない入力の一部です。
USPS DPV の確認	uspsData.dpvConfirmation が N または空の場合、住所に問題がある可能性があります。このフィールドは、米国の住所でのみ使用できます。uspsData.dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。

住所の修正例

CONFIRM_ADD_SUBPREMISES シグナル（米国の住所のみ）

Address Validation API レスポンスで、住所に建物番号が欠落している可能性があることが示された場合は、住所を確認して建物番号を追加することをお客様に伝えます。このような場合、建物の住所は有効である可能性が高いですが、結果の住所がお客様が意図したものであることを確認する必要があります。

住所の検証 API レスポンスの次のフィールドは、verdict.possibleNextAction に加えて、住所にサブプレミスがない可能性が高いかどうかを判断するために使用できます。

Missing subpremise component	address.missingComponentTypes フィールドに subpremise の値が含まれている場合、住所に部屋番号が欠落していることを示します。 注: フィールドに subpremise 以外のタイプが含まれている場合、アクションは修正カテゴリに分類されます。コンポーネント タイプの一覧については、ジオコーディングのドキュメントをご覧ください。
USPS DPV の確認	uspsData.dpvConfirmation が S の場合、住所のプライマリ番号が USPS データベース内の住所に一致しています。ただし、アドレスには副番号も含まれていることが想定されていました。このフィールドは、米国の住所でのみ使用できます。uspsData.dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。

サブプレミス住所の例を追加

CONFIRM シグナル

判定結果で、Address Validation API が検証済みの住所を生成するために住所の構成要素を推測または変更したことが示されている場合は、住所を確認します。このような場合、配送先住所はありますが、その住所がお客様が意図した住所であることを確認したい場合。

住所の軽微な問題があるかどうか、問題の内容を判断するには、verdict.possibleNextAction に加えて、Address Validation API レスポンスの次のフィールドを使用できます。

検証の粒度	住所の validationGranularity が ROUTE または PREMISE_PROXIMITY の場合、住所が正しくない可能性があります。
推論データ	hasInferredComponents フィールドが true の場合、API が他の住所コンポーネントから収集した情報を入力したことがわかります。
置換されたデータ	hasReplacedComponents フィールドが true の場合、API は入力されたデータを、アドレスを有効にすると判断したデータに置き換えました。
スペル修正	hasSpellCorrectedComponents フィールドが true の場合、API は誤字脱字のあるコンポーネントのスペルを修正しました。

住所の確認例

ACCEPT シグナル

Address Validation API API レスポンスから、その住所が配達可能であり、ダウンストリーム プロセスでお客様の操作なしで使用できることが十分に高い確度で示されている場合は、その住所を承認できます。

注: 住所を承認するか、お客様に詳細情報を尋ねるかを判断する際は、リスクレベルを考慮してください。

アドレスの品質が許容されるかどうかを判断するには、verdict.possibleNextAction に加えて、Address Validation API レスポンスの次のフィールドを使用できます。

検証の粒度	validationGranularity が PREMISE の場合、多くの場合問題ありませんが、ROUTE の値でも配達可能な住所を表す場合があります。
推定データなし	hasInferredComponents フィールドが false の場合、出力内のコンポーネントが推論されていないことを意味します。
置き換えられたデータなし	hasReplacedComponents フィールドが false の場合、入力データが置き換えられていないことを意味します。
スペル修正なし	hasSpellCorrectedComponents フィールドが false の場合、スペル修正は行われていません。
USPS DPV の確認	uspsData.dpvConfirmation が Y の場合、住所が USPS データベース内の住所と一致したことを意味します。このフィールドは、米国の住所でのみ使用できます。uspsData.dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。

許可される住所の例