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

目標

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

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

ユースケース

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

テスト

何千もの住所を実行して 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=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

  • 利用規約に基づき、住所の検証時に addressComplete,validationGranularity and validationFlags をキャッシュすることはヘッドレス方式です。

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

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

詳しくは、実際のデータ構造をご覧ください。

ステップ 2:

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

図 B: ユーザーの同意フローのエンドツーエンドの統合がどのように行われるのかを示した図。

alt_text

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

    • addressComplete は true です
    • 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 にオープンソース ライブラリとして High Volume Address Validation のリファレンス実装を公開しました。大量の住所確認（Address Validation）を迅速に開始するには、こちらをご確認ください。さまざまなシナリオでのライブラリの使用方法についての設計パターンに関する記事もご覧ください。

次のステップ

「Ensure checkout, delivery, and operations with full address 」ホワイトペーパーをダウンロードして、「Address Validation による購入手続き、配送、運用の改善 」ウェブセミナーをご覧ください。

関連情報:

作成・変更者

この記事は Google が管理しています。次の投稿者が最初に書いたものです。
プリンシパル著者:

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