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

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 に設定されます。

リファレンス ガイドの判定結果とアドレスにある addressComplete をご覧ください。

住所の品質

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

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

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

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

address プロパティは、リクエストで指定された処理済みの住所の形式と、住所のコンポーネント レベルの概要（住所のスペルミス、間違った部分の置き換え、推測された欠落部分など）を提供します。

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

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

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

geocode プロパティ

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

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

metadata プロパティ

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

詳しくは、Address Validation API の対象範囲と Address metadata のリファレンスをご覧ください。

uspsData プロパティ

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

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