Address Validation API は、住所を入力として受け取ります。API は、以下を含むレスポンスを返します。
住所全体の検証と、各住所要素（番地、建物名、市区町村など）の検証の判定。
API によって指定された完全な住所を含む 1 つの文字列。
API によって指定された住所の各要素を含む個々のプロパティ。
不足している住所コンポーネント、未確認の住所コンポーネント、解決できなかった住所コンポーネントのリスト。
住所のジオコード。
「US」と「PR」地域の場合、住所の USPS データ。
API レスポンスを使用すると、ニーズに必要な品質でアドレスが存在することを確認できます。API からのレスポンスで、住所が不完全または正しくないと判断された場合は、ユーザーに住所の更新を求めることができます。ユーザーが更新が完了したら、API を使用して更新された住所を検証します。
このドキュメントでは、API レスポンスの処理方法と、API によって検出された入力アドレスの一般的なエラーの処理方法について説明します。
注: 入力アドレスに関するエラーを API がどのように処理するかについて理解を深めるには、デモをお試しください。このデモでは、住所を入力して、レスポンスを可視化されたコンテンツと JSON オブジェクトとして表示できます。
回答について
検証レスポンスを表す JSON オブジェクトには、result 型、ValidationResult、responseID 型の 2 つのトップレベル プロパティが含まれます。
{
"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 プロパティには次のプロパティが含まれています。
inputGranularity入力住所の粒度を示します。この粒度は住所の解析は行いませんが、検証は行いません。たとえば、これらのプロパティには、建物レベルの結果に解決される住所に
PREMISE、ブロックに解決される住所にBLOCK、道路（道路、道路、高速道路など）までの詳細な住所にROUTEを含めることができます。validationGranularityAPI が住所を検証できる粒度を示します。これは、検証された住所の粒度であり、
address.formattedAddressまたはaddress.postalAddressで返される住所の粒度ではありません。geocodeGranularity生成されたジオコーディングの場所の粒度を示します。
addressCompleteAPI によって住所が完全であると見なされる場合は true になります。つまり、
addressプロパティに、未解決のトークン（住所文字列またはシンボル）、予期しない住所コンポーネント、住所コンポーネントの欠落がないことを意味します。hasUnconfirmedComponents、hasInferredComponents、hasReplacedComponents少なくとも 1 つの住所コンポーネントが分類または検証できないかどうか、入力に含まれていない住所コンポーネントが 1 つ以上推定（追加）された場合、少なくとも 1 つの住所コンポーネントが置き換えられたかどうかを示すプロパティ。
推定されるコンポーネントが含まれる完全な住所かどうかの判定
次の例は、推定されるコンポーネントを含む完全な住所の verdict プロパティを示しています。
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
粒度は前提に解決され、住所は完全ですが、API は一部のコンポーネントの値を推測しました。この例では、API が残りの住所から推測できる米国の郵便番号は、入力住所からは省略されています。より詳細な例については、推定住所コンポーネントをご覧ください。
住所の構成要素が未確認かどうかの判定
推定される構成要素がある場合でも、入力された住所は完全であるとみなすことはできませんが、未解決の住所トークン、予期しない住所要素、住所要素の欠落がある場合、その住所は完全な住所とは見なされません。
次の例では、hasUnconfirmedComponents が true に設定されており、分類または検証できない住所コンポーネントが住所に 1 つ以上あることを示しています。
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true,
"hasInferredComponents": true
}
この場合、検証されてジオコーディングされた住所の粒度は OTHER に設定され、住所が完全でないことを示すために addressComplete プロパティはレスポンスから除外されます。詳細な例については、住所コンポーネントが未確認または未確認をご覧ください。
回答例
以降のセクションでは、完全な住所や一般的な住所検証エラーなど、さまざまなシナリオでのレスポンスについて説明します。この例では次のようになります。
レスポンスに
trueに設定されたaddressCompleteが含まれている場合、API は入力アドレスが良質であると判断しています。Address Validation API により、住所に大幅な変更が行われたこと、または住所にエラーがあることが判明した場合は、返された住所を顧客に確認する必要があります。
質の高い完全な住所
API は住所が完全なものであると判断すると、レスポンスの verdict プロパティで addressComplete を true に設定します。
次に例を示します。
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true
}
レスポンスの address プロパティには、API によって判定された住所のすべての詳細情報が含まれます。レスポンスには formattedAddress プロパティが含まれます。このプロパティには、修正および検証された住所が 1 行の文字列として含まれます。完全な住所として formattedAddress フィールドに含まれる 1 行の住所を使用することをおすすめします。米国では、大文字表記や ZIP+4 など、わずかな修正や追加が含まれる場合があるからです。
また、address プロパティは、各住所コンポーネントについて、API が判別した問題の有無を示します。通りの名前や都市などのコンポーネントごとに、address フィールドに confirmationLevel フィールドがあります。有効な値は次のとおりです。
CONFIRMEDは、コンポーネントが存在することを API が確認できたことを示します。UNCONFIRMED_BUT_PLAUSIBLEは、コンポーネントを確認できなかったものの、妥当な可能性があることを示します。UNCONFIRMED_AND_SUSPICIOUSは、コンポーネントが未確認で、間違っている可能性があることを示します。
次に例を示します。
"address": {
// Validated address as a single string.
"formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
// Individual validated address components.
"postalAddress": {
"regionCode": "US",
"languageCode": "en",
"postalCode": "94043-1351",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1600 Amphitheatre Pkwy"
]
},
// Validation results for each component.
"addressComponents": [
{
"componentName": {
"text": "1600",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "Amphitheatre Pkwy",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "CONFIRMED"
},
…
]
// List of any missing, unconfirmed, or unresolved address components.
// These properties are omitted from the response if they are empty.
"missingComponentTypes": [],
"unconfirmedComponentTypes": [],
"unresolvedTokens": []
}
推定される住所コンポーネント
入力住所に完全な住所が含まれていない場合、API は不足している住所コンポーネントをレスポンスに追加しようとします。こうした追加されたコンポーネントを、推定住所コンポーネントといいます。
たとえば、次の入力アドレスを使用します。
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1600 Amphitheatre Pkwy"]
}
}
この入力住所には米国の郵便番号が含まれていません。API は、残りの入力アドレスから郵便番号を特定し、レスポンスに追加します。
この例では、verdict プロパティで hasInferredComponents を true に設定し、API が 1 つ以上のコンポーネントの値を推定したことを示します。ただし、これは軽微な修正であるため、API は addressComplete を true に設定して、入力アドレスがまだ高品質であることを示します。
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
推定されたコンポーネントについて、API は address プロパティの addressComponents 配列の対応する要素で inferred を true に設定します。
{
"componentName": {
"text": "94043"
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
入力された住所のスペルミス
入力した住所のスペルミス（市区町村や都道府県名の入力ミスなど）はよくあることです。たとえば、住所の地域区分の部分として、「Mountain View」ではなく「MontainView」と入力します。
{
"address": {
"regionCode" : "US",
"locality" : "MontainView",
"addressLines" : ["1600 Amphitheatre Pkwy"]
}
}
この例では、verdict プロパティが 1 つ以上のコンポーネントの値を推測したことを示しています。また、addressComplete を true に設定して、入力アドレスが依然として住所を解決できたため高品質であったことを示しています。
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
API は住所を正しいスペルに解決しようとします。address プロパティの addressComponents 配列内の対応する住所要素には、text プロパティ内の修正された文字列が表示されます。また、spellCorrected を true に設定することで、スペルミスがあったことを示します。
{
"componentName": {
"text": "Mountain View",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED",
"spellCorrected": true
}
住所コンポーネントが未確認または未確認
ユーザーは入力された住所の一部を省略できます。以下の例では、ユーザーは番地を入力しますが、番地は入力しません。
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"addressLines": ["1600"]
}
}
この場合、API が住所を解決するための情報の欠落が多すぎるため、判定で addressComplete プロパティが省略されます。また、API は hasUnconfirmedComponents を true に設定し、住所に未確認のコンポーネントがあることを示します。
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true,
"hasInferredComponents": true
}
また、API がアドレスを解決できなかったため、validationGranularity と geocodeGranularity が OTHER に設定されています。
address プロパティの addressComponents 配列で、API によって番地コンポーネントが UNCONFIRMED_BUT_PLAUSIBLE としてマークされます。
{
"componentName": {
"text": "1600",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}
最後に、API は address プロパティの missingComponentTypes 配列と unconfirmedComponentTypes 配列に、入力で不足しているコンポーネントと確認できなかったコンポーネントを格納します。
"missingComponentTypes": [
"route",
"postal_code"
],
"unconfirmedComponentTypes": [
"street_number"
]
さまざまな粒度の値を理解する
レスポンスの粒度の値から、API による住所の解釈がどの程度粗いか、またはどの程度詳細かに関する分析情報が得られます。たとえば、次の入力アドレスを使用します。
{
"address": {
"regionCode": "US",
"locality": "Northampton",
"addressLines": ["6 South Main Street APT 456"]
}
}
この例では、API は USPS データベースで番地を検索しますが、アパート番号を見つけることはできません。また、API は番地「6」の正確なジオコードを見つけられませんが、「4」と「8」のジオコードを見つけることができます。この場合、API は次の verdict を返します。
"verdict": {
"inputGranularity": "SUB_PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete": true,
"hasUnconfirmedComponents": true,
"hasInferredComponents": true
}
レスポンス:
API が入力アドレスをアパート レベルまで解析できるため、
inputGranularityはSUB_PREMISEです。inputGranularityは、入力住所を解析する API 機能にのみ適用されます。住所に対して行われる検証には適用されません。validationGranularityはPREMISEです。API は番地「6」の存在は検証できますが、「APT 456」は検証できないためです。API で「APT 456」を検証することはできませんが、出力のformattedAddressフィールドとpostalAddressフィールドには含まれます。geocodeGranularityはPREMISE_PROXIMITYです。これは、API がジオコーディングの位置情報の補間のみを行い、入力された正確な住所のジオコードが見つからないためです。
人為的に作成された住所が USPS によって検出されました
USPS が人為的に作成された住所を特定した場合、レスポンスの uspsData プロパティの errorMessage フィールドに、問題を説明するエラー メッセージが含まれます。次に例を示します。
"uspsData": {
"errorMessage": "AMS API processing was terminated due to the detection of
what is determined to be an artificially created address. No address beyond
this point has been validated and/or processed. If you believe this address
was identified in error, please contact your Vendor."
}
人為的に作成した住所を API に送信すると、USPS データベースにアクセスできなくなる可能性があります。このエラー メッセージが表示された場合は、API に人為的なアドレスが送信されないようにアドレスの送信元を調査することをおすすめします。
このセキュリティ対策は、送信された住所が人為的に作成されたもので、合法的に取得されていない可能性があることを検出して、アドレスリストが人為的に作成されるのを防ぐためのものです。このような状況はめったに発生しません。