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

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
}

以下のセクションでは、verdict プロパティ内のすべてのフィールドの概要を示します。

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

住所の粒度

住所の粒度とは、住所またはジオコードの特異性を判断するために使用される詳細レベルを指します。validationGranularity レスポンスにおける住所の特異性は、住所が配送可能かどうかを示す重要なシグナルです。

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

  • inputGranularity - Address Validation API に送信された住所から取得される詳細レベル。リクエスト内の住所の詳細レベルは、検証レスポンスの住所の詳細レベルに影響します。たとえば、inputGranularity がレベルより PREMISE 低い住所でも、通常は validationGranularityPREMISE レベルになることはありません。
  • validationGranularity - Address Validation API が住所を完全に検証できる粒度。ほとんどの場合、PREMISE または SUB_PREMISE の粒度は、配達可能な可能性が高い住所を示します。
  • geocodeGranularity - 住所に関連付けられているジオコードの詳細レベルを記述します。たとえば、Google の記録に、マンション名があるが、大きな集合住宅内にあるそのアパートの正確な場所は示されていないことがあります。この場合、validationGranularitySUB_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 プロパティ

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

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