検証ロジックを構築する

このドキュメントでは、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 つのアクションをまとめます。

1. 修正、確認、承認の動作に基づく使用するワークフロー 。
2. レスポンスから確認する最初のシグナル 。ここで説明するシグナルは verdict プロパティからのものであり、確認するシグナルはこれだけではありません。ただし、住所の品質の最初の指標となります。 各動作タイプは、このドキュメントのセクションに対応しており、調査する必要があるその他のシグナルについて説明しています。

システムの動作
住所を修正する	verdict からのレスポンスは、提供する必要がある重要な情報が不足していることを示しています。API から返される住所は、配送可能な品質ではない可能性があります。 ワークフロー 必要に応じて住所のコンポーネントを調査します。 お客様に住所の問題を修正するよう促します。 更新された住所の検証をリクエストします。 住所で続行します。 判定シグナル 次のいずれか に該当します。 validationGranularity が OTHER に設定されている。 addressComplete が false である。
住所を確認する	verdict からのレスポンスは、配送可能な 住所を示していますが、元の入力に変更が加えられています。スペルが修正されたデータ、または確認できるデータが推測されています。 ワークフロー 修正が必要な場合: 必要に応じて住所のコンポーネントを調査します。 更新された住所の検証をリクエストします。 住所で続行します。 修正が不要な場合: 住所で続行します。 判定シグナル 次のすべて に該当します。 validationGranularity に ROUTE が含まれている。 addressComplete が true である。 hasInferredComponents フィールドが true または hasReplacedComponents フィールドが true である。
住所を承認する	Address Validation API レスポンスは、高品質の住所を示しています。 ワークフロー 返された住所で続行します。 判定シグナル 次のすべて に該当します。 validationGranularity に PREMISE 以上が含まれている。 addressComplete が true である。 推測されたコンポーネントまたは置換されたコンポーネントがない 。

実装に関するアドバイス

システムが住所検証シグナルにどのように応答するかを設計する際は、次の推奨事項がより効果的なレスポンス モデルの構築に役立ちます。ただし、これらは推奨事項にすぎないため、実装はビジネスモデルに適したものにする必要があります。

	ガイダンス	詳細
リスクレベル	修正を求めることと、入力した住所を承認することのバランスを取る際は、状況に対する許容レベルを考慮してください。	Address Validation API は、検証プロセスを最適化するためにリスクレベルに組み込むことができるさまざまなシグナル を返します。 たとえば、住所に未確認の番地が含まれている場合でも、承認できます。一方、ビジネス オペレーションで より正確な住所が必要な場合は、ユーザーに確認を求めることができます。どちらのカテゴリにも該当する可能性がある例については、「住所を承認する - 例」の米国外の未確認の番地をご覧ください。
住所を承認する	お客様がプロンプトに応答しない場合は、システムが元の入力を承認できるようにすることをおすすめします。	このような場合、お客様がシステムにない住所（新築など）を入力した可能性があります。

デモをお試しください。 このドキュメントでは、上記の修正、確認、承認のフロープロセスを理解できるように、さまざまな例 を使用しています。これらの例の結果を確認するには、 Maps JavaScript API の Address Validation デモに入力します。

住所を修正する

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

修正シグナル

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. 検証の粒度

validationGranularity が ROUTE 以上の場合は許容されますが、PREMISE または SUBPREMISE の場合は配送可能性のシグナルがより強くなります。

2. その他のシグナル

お客様に住所の入力を確認するかどうかを決定する際、判定では、調査するコンポーネントを特定するために次の情報も提供されます。

推測されたデータ	hasInferredComponents フィールドが true の場合、API が他の住所コンポーネントから収集した情報を入力したことがわかります。
置換されたデータ	hasReplacedComponents フィールドが true の場合、 API は入力されたデータを、住所を有効にするために必要と判断したデータに置き換えました。

3. 米国の住所シグナル

米国の住所にのみ適用される特定のフィールドは、ロジックでお客様に詳細を確認する必要があることを示しています。次のいずれかに該当します。

dpvConfirmation	S dpvConfirmation の詳細については、 米国の住所を処理するをご覧ください。
住所レスポンス	`missingComponentTypes` フィールドが含まれています。値は `subpremise` です。 注: フィールドにタイプ subpremise以外のタイプが含まれている場合、アクションは 住所の修正カテゴリに分類されます。住所タイプの完全なリストについては、 ジオコーディングのドキュメント をご覧ください。

住所の確認例

住所を承認する

住所を承認するのは、判定で住所が配送可能であり、ダウンストリーム プロセスでお客様の操作なしで使用できることが高い信頼度で示されている場合です。

承認シグナル

Address Validation API は、住所を確認する必要があるかどうかを知らせるさまざまなシグナルを提供します。

1. 検証の粒度

validationGranularity が PREMISE 以上の場合は許容されますが、場合によっては ROUTE でも配送可能な住所を示します。

2. その他のシグナル

高品質の住所の判定では、次の情報も提供されます。

• 置換されたデータがない 。この場合、hasReplacedComponents: FALSE。
• 推測されたコンポーネントがない 。この場合、hasInferredComponents: FALSE。

3. 米国の住所シグナル

米国の住所にのみ適用される特定のフィールドは、配送可能な高品質の住所を示しています。許容される米国の住所の場合は、次のようになります。

dpvConfirmation	Y dpvConfirmation の詳細については、米国の住所を処理するをご覧ください。

住所の承認例