基本的な住所確認のレスポンスについて

Address Validation API のレスポンスには、次の最上位プロパティが含まれます。

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // The geocode generated for the input address.
  "geocode": {},
  // Information indicating if the address is a business, residence, etc.
  "metadata": {},
  // Information about the address from the US Postal Service
  // ("US" and "PR" addresses only).
  "uspsData": {},
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

verdict プロパティ

verdict プロパティは、Address Validation の結果を要約したもので、住所確認ロジックを構築する際に最初に評価するプロパティです。このプロパティは、出力アドレスの品質に応じて、さまざまなフィールドを返すことができます。たとえば、次の例は、品質の高い住所の verdict プロパティを示しています。この特定のリクエストに対して、次のフィールドが返されます。

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

以降のセクションでは、verdict プロパティのすべてのフィールドについて説明します。

リファレンス ガイドの判定をご覧ください。

住所の粒度

住所の粒度とは、住所またはジオコードの具体性を判断する際に使用される詳細レベルを指します。validationGranularity レスポンスのアドレスの具体性は、アドレスが配送可能かどうかを判断する重要なシグナルです。

verdict プロパティは、次の粒度シグナルを返します。

  • inputGranularity - Maps JavaScript API の Address Validation に送信された住所から取得された詳細レベルを示します。リクエストに含まれる住所の詳細レベルは、検証レスポンスに含まれる住所の詳細レベルに影響します。たとえば、PREMISE レベル未満の inputGranularity を持つアドレスは、通常、PREMISE レベルへの validationGranularity にはなりません。
  • validationGranularity - Maps JavaScript API の Address Validation で住所を完全に検証できる粒度レベル。ほとんどの場合、PREMISE または SUB_PREMISE の粒度レベルは、配送可能な品質の高い住所であることを示します。
  • geocodeGranularity - 住所に関連付けられたジオコードの詳細レベルを示します。たとえば、Google の記録にアパートの部屋番号が存在することが示されていても、大規模なアパート群内の特定の部屋の正確な位置が示されていない場合があります。この場合、validationGranularity は SUB_PREMISE ですが、geocodeGranularity は PREMISE です。
リファレンス ガイドの粒度をご覧ください。

住所の完全性

判定では、高品質な住所のシグナルとして addressComplete プロパティが返されます。具体的には、欠落しているコンポーネント、未解決のコンポーネント、予期しないコンポーネントがないことを意味します。

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

住所に欠落しているコンポーネント、未解決のコンポーネント、予期しないコンポーネントがある場合、このフィールドは false に設定されます。

リファレンス ガイドの判定と住所の addressComplete をご覧ください。

住所の品質

いくつかのフィールドは、住所コンポーネントの問題、または住所コンポーネントの調整（住所コンポーネントの推測や欠落など）を示します。たとえば、次の verdict プロパティは、未確認のコンポーネントがあり、addressComplete フィールドが欠落している住所を示しています。

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
リファレンス ガイドの判定をご覧ください。

考えられる次のアクション

possibleNextAction 判定フィールドには、API レスポンスの解釈の概要が表示されます。これは、次に取るべきアクションを決定する際に役立ちます。このフィールドは API レスポンスの他のフィールドから派生したものであり、住所の正確性や配送可能性を保証するものではありません。

address プロパティと addressComponent プロパティ

address プロパティは、リクエストで指定された処理済みのアドレスの書式設定と、アドレスのコンポーネント レベルの概要（アドレスのスペルミス、置換された不正確な部分、推測された欠落部分など）を提供します。

リファレンス ガイドの Address をご覧ください。

addressComponent プロパティは address のサブコンポーネントで、Maps JavaScript API の Address Validation が処理した住所の要素（コンポーネント）の詳細なリストを提供します。API は、各コンポーネント フィールドを名前、タイプ、確認レベルで識別します。

リファレンス ガイドの addressComponent をご覧ください。

geocode プロパティ

geocode プロパティは、入力された住所に関連付けられたジオコーディングされた場所を示します。このプロパティは、プレイス ID など、場所自体に関する詳細情報を提供します。

リファレンス ガイドの Geocode をご覧ください。

metadata プロパティ

このプロパティは、Maps JavaScript API の Address Validation で処理されるすべての住所に入力されるとは限りませんが、住所が住宅、ビジネス、私書箱のいずれであるかを示します。

Address Validation API の対象地域と Address metadata のリファレンスをご覧ください。

uspsData プロパティ

このプロパティは、米国の住所に関する有用な情報を提供します。ただし、サービスによって検証されたすべての住所に完全に入力されるとは限りません。そのため、このプロパティをアドレスの検証の唯一の手段として使用するのではなく、verdict と address も確認する必要があります。

米国の住所を処理すると USPSData のリファレンスをご覧ください。