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

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 に送信された住所から取得される詳細レベルを指定します。リクエスト内の住所の詳細レベルは、検証レスポンスの住所の詳細レベルに影響します。たとえば、PREMISE 未満の inputGranularity を持つアドレスは、通常、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 も確認してください。