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

Address Validation API は、2 つの最上位プロパティを含む JSON オブジェクトとしてレスポンスの本文を提供します。

• result: ValidationResult 型のオブジェクト
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // 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"
}

このドキュメントでは、result オブジェクトについて説明します。responseID について詳しくは、更新された住所を処理するをご覧ください。

verdict プロパティ

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

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

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

アドレスの粒度

住所の粒度とは、住所またはジオコードの特定の場所を決定するために使用される詳細レベルのことです。validationGranularity レスポンスの住所の詳細は、住所が配達可能かどうかを判断するための重要なシグナルです。

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

• inputGranularity - Address Validation API に送信された住所から取得される詳細レベルを指定します。リクエストに含まれる住所の詳細レベルは、検証レスポンスの住所の詳細レベルに影響します。たとえば、inputGranularity が PREMISE レベルより下の住所の場合、通常は validationGranularity が PREMISE レベルになることはありません。
• validationGranularity - Address Validation API が住所を完全に検証できる粒度レベル。ほとんどの場合、PREMISE または SUB_PREMISE の粒度レベルは、配達が可能な可能性が高い優良な住所を示します。
• geocodeGranularity - 住所に関連付けられているジオコードの詳細レベルを表します。たとえば、Google のレコードでアパート番号の存在は示されているものの、大きな集合住宅内の特定のアパートの正確な位置は示されていない場合があります。この場合、validationGranularity は SUB_PREMISE ですが、geocodeGranularityisPREMISE` です。

住所の完全性

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

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

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

住所の品質

いくつかのフィールドは、住所コンポーネントの問題、または住所コンポーネントの推定や欠落などの調整を示します。たとえば、次の verdict プロパティは、住所のコンポーネントが確認されておらず、addressComplete フィールドが欠落していることを示しています。

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

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

address プロパティには、リクエストで指定された処理済みの住所のフォーマットと、住所のコンポーネント レベルの概要（住所のスペルミス、間違った部分の置換、推定された不足部分など）が含まれます。

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

geocode プロパティ

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

metadata プロパティ

このプロパティは、Address Validation API によって処理されるすべての住所に入力されない場合がありますが、住所が住宅、ビジネス、私書箱のいずれのタイプであるかを示します。

uspsData プロパティ

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