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

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

{
  "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,
  "possibleNextAction": "ACCEPT"
}

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

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

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

possibleNextAction プロパティは、API レスポンスの残りの部分の解釈的な概要を提供します。これは、お客様に住所の確認や編集を促す必要があるかどうかを判断するのに役立ちます。詳細については、検証ロジックを構築するをご覧ください。

住所の粒度

住所の粒度とは、住所やジオコードの特定性を判断する際に使用される詳細レベルのことです。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,
    "possibleNextAction": "ACCEPT"
}

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

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

住所の品質

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

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

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 のリファレンスをご覧ください。
前へ
住所確認リクエストを送信する
次へ
検証ロジックを作成する