Address Validation API を使用して大量のアドレスを処理する

目標

デベロッパーは、品質が低い可能性がある顧客住所を含むデータセットを扱うことがよくあります。お客様の身分証明書の確認から配送まで、さまざまなユースケースで住所が正しいことを確認する必要があります。

Address Validation API は、住所の検証に使用できる Google Maps Platform のプロダクトです。ただし、一度に処理できるのは 1 つのアドレスのみです。このドキュメントでは、API テストから 1 回限りと定期的な住所検証まで、さまざまなシナリオで大規模な住所検証を使用する方法について説明します。

ユースケース

次に、大量の住所検証が役立つユースケースについて説明します。

テスト

多くの場合、Address Validation API をテストするには、数千のアドレスを実行する必要があります。住所がカンマ区切り値ファイルに保存されていて、住所の品質を確認したい場合。

住所の 1 回限りの確認

Address Validation API にオンボーディングする際に、既存の住所データベースをユーザー データベースと照合します。

住所の定期的な検証

住所を定期的に検証する必要があるシナリオはいくつかあります。

  • 1 日の間に取得された住所の詳細（顧客登録、注文の詳細、配送スケジュールなど）を検証するジョブをスケジュール設定している場合があります。
  • 営業部門からマーケティング部門など、さまざまな部門から住所を含むデータダンプが届く場合があります。住所を受け取る新しい部門は、多くの場合、使用する前に住所を検証したいと考えています。
  • 住所は、アンケートや各種プロモーションの際に収集し、後でオンライン システムで更新します。システムに住所を入力する際に、住所が正しいことを確認したい。

技術的な詳細

このドキュメントでは、以下のことを前提としています。

  • 顧客データベース（顧客の詳細を含むデータベース）の住所を使用して Address Validation API を呼び出している
  • データベース内の個々のアドレスに対して有効性フラグをキャッシュに保存できます。
  • 有効性フラグは、個々のお客様がログインしたときに Address Validation API から取得されます。

本番環境用のキャッシュ

Address Validation API を使用する場合は、API 呼び出しからのレスポンスの一部をキャッシュに保存することがよくあります。利用規約では、キャッシュに保存できるデータが制限されていますが、Address Validation API からキャッシュに保存できるデータは、ユーザー アカウントに対してキャッシュに保存する必要があります。つまり、データベースで、住所または住所のメタデータをユーザーのメールアドレスまたは他のプライマリ ID に対してキャッシュに保存する必要があります。

大量の住所検証のユースケースでは、データ キャッシュは、第 11 章 3 項に記載されている Address Validation API のサービス固有の利用規約に従う必要があります。この情報に基づいて、ユーザーの住所が無効であるかどうかを判断できます。無効な場合は、次回アプリを操作する際にユーザーに正しい住所を入力するよう求めるメッセージを表示します。

  • AddressComponent オブジェクトのデータ
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

実際の住所に関する情報をキャッシュに保存する場合は、ユーザーの同意を得たうえでのみキャッシュに保存する必要があります。これにより、ユーザーは特定のサービスが住所を保存する理由を十分に理解し、住所の共有に関する利用規約に同意していることを確認できます。

ユーザーの同意の例としては、購入手続きページで e コマースの住所フォームを直接操作することがあります。荷物を配送する目的で住所をキャッシュに保存し、処理することを理解しています。

ユーザーの同意を得たうえで、レスポンスから formattedAddress などの重要なコンポーネントをキャッシュに保存できます。ただし、ヘッドレス シナリオでは、住所の検証がバックエンドで行われるため、ユーザーは同意を提供できません。したがって、このヘッドレス シナリオでは、非常に限られた情報をキャッシュに保存できます。

レスポンスの内容

Address Validation API レスポンスに次のマーカーが含まれている場合、入力アドレスは配送可能な品質であると確信できます。

  • Verdictオブジェクトの addressComplete マーカーが true である。
  • Verdict オブジェクトの validationGranularity が PREMISE または SUB_PREMISE である
  • AddressComponent のいずれにも、次のようにマークされていません。
    • Inferred（注: inferred=trueaddressComplete=true の場合に発生することがあります）
    • spellCorrected
    • replaced
    • unexpected、
  • confirmationLevel: AddressComponent の確認レベルが CONFIRMED または UNCONFIRMED_BUT_PLAUSIBLE に設定されている

API レスポンスに上記のマーカーが含まれていない場合、入力アドレスの品質が低い可能性があります。その場合は、データベースにフラグをキャッシュに保存して反映できます。キャッシュに保存されたフラグは、アドレス全体の品質が低いことを示します。スペルが修正済みなど、より詳細なフラグは、アドレスの品質に関する特定の問題を示します。品質が低いと報告された住所についてお客様とやり取りする際は、既存の住所を使用して Address Validation API を呼び出します。Address Validation API は、修正済みの住所を返します。この住所は、UI プロンプトを使用して表示できます。お客様がフォーマットされた住所を承認したら、レスポンスから以下をキャッシュに保存できます。

  • formattedAddress
  • postalAddress
  • addressComponent componentNames または
  • UspsData standardizedAddress

ヘッドレス住所検証を実装する

上記の説明に基づいて、

  • ビジネス上の理由から、Address Validation API からのレスポンスの一部をキャッシュに保存することがよくあります。
  • ただし、Google Maps Platform の利用規約では、キャッシュに保存できるデータが制限されています。

次のセクションでは、利用規約に準拠し、大量の住所検証を実装する 2 段階のプロセスについて説明します。

ステップ 1:

最初のステップでは、既存のデータ パイプラインから大量のアドレス検証スクリプトを実装する方法について説明します。このプロセスにより、利用規約に準拠した方法で、Address Validation API レスポンスの特定のフィールドを保存できます。

図 A: 次の図は、大規模な住所検証ロジックでデータ パイプラインを拡張する方法を示しています。

alt_text

利用規約に基づき、addressComponent から次のデータをキャッシュに保存できます。

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

したがって、実装のこのステップでは、上記のフィールドを UserID に対してキャッシュに保存します。

詳細については、実際のデータ構造の詳細をご覧ください。

ステップ 2:

ステップ 1 では、入力データセット内の一部の住所の品質が低い可能性があるというフィードバックを収集しました。次のステップでは、報告された住所をユーザーに提示し、保存されている住所を修正する同意を得ます。

図 B: この図は、ユーザーの同意フローのエンドツーエンドの統合の例を示しています。

alt_text

  1. ユーザーがログインしたときに、まずシステムに検証フラグがキャッシュに保存されているかどうかを確認します。
  2. フラグがある場合は、住所を修正して更新するための UI をユーザーに表示する必要があります。
  3. 更新済みまたはキャッシュに保存された住所を使用して Address Validation API を再度呼び出し、修正済みの住所をユーザーに提示して確認できます。
  4. 住所の品質が高い場合、Address Validation API は formattedAddress を返します。
  5. 修正が加えられた場合はその住所をユーザーに提示し、修正が加えられていない場合は黙って承認します。
  6. ユーザーが同意すると、formattedAddress をデータベースにキャッシュに保存できます。

まとめ

大量の住所の検証は、多くのアプリケーションで発生する一般的なユースケースです。このドキュメントでは、Google Maps Platform 利用規約に準拠したこのようなソリューションを実装する方法について、いくつかのシナリオと設計パターンを示します。

また、GitHub でオープンソース ライブラリとして、大規模なアドレス検証のリファレンス実装を作成しました。ぜひチェックしてみてください。大量の住所の処理をすぐに構築できます。さまざまなシナリオでライブラリを使用する方法の設計パターンに関する記事もご覧ください。

次のステップ

確実な住所で購入手続きと配送を改善する ホワイトペーパーをダウンロードし、Address Validation で購入手続き、配送、オペレーションを改善する ウェビナーをご覧ください。

おすすめの関連情報:

寄稿者

この記事は Google が管理しています。以下は、このガイドを最初に作成したコントリビューターです。
主な作成者:

Henrik Valve | ソリューション エンジニア
Thomas Anglaret | ソリューション エンジニア
Sarthak Ganguly | ソリューション エンジニア