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
ですが、geocodeGranularity
is
PREMISE になります。
リファレンス ガイドの粒度をご覧ください。 |
住所の完全性
判定の結果、高品質の住所のシグナルとして 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 のリファレンスをご覧ください。 |