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

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 プロパティは、住所の検証結果をまとめたもので、住所チェック ロジックを構築する際に最初に評価すべきプロパティです。このプロパティは、出力住所の品質に応じてさまざまなフィールドを返すことができます。たとえば、次の例は、品質の良い住所の verdict プロパティを示しています。この特定のリクエストに対して次のフィールドが返されます。

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

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

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

住所の粒度

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

verdict プロパティは、次の粒度��シ���ナル��������ます。

  • inputGranularity - Maps JavaScript API の Address Validation に送信された住所から取得された詳細レベルを表します。リクエストのアドレスの詳細レベルは、検証レスポンスのアドレスの詳細レベルに影響します。たとえば、inputGranularity が PREMISE レベルを下回るアドレスは、通常、validationGranularity が PREMISE レベルになることはありません。
  • 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 に設定されます。

リファレンス ガイドの Verdictとアドレスの addressComplete をご覧ください。

住所の品質

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

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

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

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 API の対象範囲と Address metadata のリファレンスをご覧ください。

uspsData プロパティ

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

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