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

目的

デベロッパーは多くの場合、顧客の住所を含むデータセットを扱います。これらのデータセットは、品質が低い可能性があります。顧客 ID の確認から配達まで、さまざまなユースケースで住所が正しいことを確認する必要があります。

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

使用例

次に、大量の住所確認が役立つユースケースを見てみましょう。

テスト

何千もの住所を実行して Address Validation API をテストしたい場合があります。カンマ区切り値ファイルにアドレスが格納されていて、その品質を検証したい場合があります。

アドレスの 1 回限りの検証

Address Validation API へのオンボーディング中に、ユーザー データベースに照らして既存の住所データベースを検証する必要があります。

住所の定期的な確認

多くのシナリオでは、住所を繰り返し確認する必要があります。

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

技術的な詳細

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

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

本番環境用のキャッシュ保存

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

大量の Address Validation ユースケースの場合、データ キャッシュは、セクション 11.3 に記載されている Address Validation API のサービス固有の規約に従う必要があります。この情報に基づいて、ユーザーの住所が無効であるかどうかを判断できます。その場合は、ユーザーが次にアプリケーションを操作するときに住所の修正を求めるメッセージを表示します。

  • Verdict オブジェクトのデータ

    • inputGranularity
    • validationGranularity
    • geocodeGranularity
    • addressComplete
    • hasUnconfirmedComponents
    • hasInferredComponents
    • hasReplacedComponents

  • AddressComponent オブジェクトのデータ

    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

実際の住所に関する情報をキャッシュに保存するには、ユーザーの同意がある場合にのみ、そのデータをキャッシュに保存する必要があります。これにより、ユーザーは特定のサービスが住所を保存する理由を十分に把握でき、住所の共有に関する利用規約に同意できます。

ユーザーの同意の例としては、購入手続きページで表示される e コマースの住所フォームを直接操作する場合が挙げられます。お客様が荷物を発送する目的で住所をキャッシュして処理することを理解している。

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

レスポンスの解釈

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

  • Verdict オブジェクトの addressComplete マーカーは true であり、
  • Verdict オブジェクトの validationGranularity が PREMISE または SUB_PREMISE である
  • どの AddressComponent も以下としてマークされていない。
    • Inferred（注: inferred=true: addressComplete=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: 次の図は、大量の Address Validation ロジックでデータ パイプラインを強化する方法を示しています。

alt_text

  • 利用規約に基づき、ヘッドレス方式でアドレスを検証する場合は addressComplete,validationGranularity and validationFlags をキャッシュに保存できます。

  • 顧客データベースの特定のユーザー ID に対する addressComplete,validationGranularity and validationFlags, PlaceID をキャッシュに保存できます。

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

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

ステップ 2:

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

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

alt_text

  1. ユーザーがログインしたら、まず、次のような検証フラグがシステムにキャッシュされていないか確認します。

    • addressComplete が正当である
    • validationGranularity が PREMISE または SUB_PREMISE でない
    • validationFlags は inferred,spellCorrected,replaced,unexpected です。
      • フラグがない場合は、既存のキャッシュ アドレスが高品質である可能性が高いため、そのアドレスを使用できます。

  2. フラグがある場合は、住所を修正または更新するための UI をユーザーに提示する必要があります。

  3. 更新後の住所またはキャッシュに保存された住所を使用して Address Validation API を再度呼び出し、修正した住所をユーザーに提示して確認してもらうことができます。

  4. 住所の品質が良ければ、Address Validation API は formattedAddress を返します。

  5. 修正が行われた場合は、その住所をユーザーに提示し、修正がない場合は暗黙的に承認します。

  6. ユーザーが承諾したら、formattedAddress をデータベースにキャッシュできます。

ステップ 2 を実装する擬似コード:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

おわりに

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

さらに、GitHub にオープンソース ライブラリとして大規模な Address Validation のリファレンス実装を公開しています。大量の住所確認を使用して迅速に構築を開始するために、ぜひご確認ください。また、さまざまなシナリオでライブラリを使用する方法に関する設計パターンに関する記事もご覧ください。

次のステップ

ホワイトペーパー「信頼できる住所で購入手続き、配達、業務を改善 」をダウンロードし、「Address Validation を使用して購入手続き、配達、業務を改善する 」ウェブセミナーをご覧ください。

関連資料:

協力者

この記事は Google が管理しています。最初に書いたのは以下の寄稿者です。
主任執筆者:

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