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

注: このドキュメントでは、高品質の住所に対する Address Validation レスポンスの基本要素について説明します。実際の住所のシナリオを処理し、より複雑なレスポンスに関するロジックを構築する方法については、 検証ロジックを構築するをご覧ください。

Address Validation API レスポンスには、次の最上位プロパティが含まれています。

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

verdict プロパティ

キーポイント: verdict プロパティを使用して、住所の品質のベースラインの概要を取得します。

verdict プロパティは、Address Validation の結果をまとめたもので、住所チェック ロジックを構築する際に最初に評価するプロパティです。このプロパティは、出力住所の品質に応じてさまざまなフィールドを返します。たとえば、次の例は、高品質の住所の verdict プロパティを示しています。このプロパティは、この特定のリクエストに対して次のフィールドを返します。

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

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

住所の粒度

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

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

• inputGranularity \- Maps JavaScript API の Address Validation に送信された住所から取得された詳細レベルを表します。リクエスト内の住所の詳細レベルは、検証レスポンス内の住所の詳細レベルに影響します。 たとえば、inputGranularity が PREMISE レベル未満の住所では、通常、validationGranularity が PREMISE レベルになることはありません。
• validationGranularity \- Maps JavaScript API の Address Validation が住所を完全に検証できる粒度レベル。ほとんどの場合、粒度レベルが PREMISE または SUB_PREMISE の場合は、配達可能な高品質の住所であることを示します。
• geocodeGranularity \- 住所に関連付けられたジオコードの詳細レベルを表します。たとえば、Google のレコードにはアパートの部屋番号が存在することが示されているが、大規模なアパートの特定の部屋の正確な位置は示されていない場合があります。この場合、 validationGranularity は SUB_PREMISE ですが、 geocodeGranularity は PREMISE です。

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

住所の完全性

判定では、高品質の住所のシグナルとして addressComplete プロパティが返されます。これは、欠落しているコンポーネント、未解決のコンポーネント、予期しないコンポーネントがないことを意味します。

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

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

注: 手動で確認したときに addressComplete プロパティが判定 に表示されない場合、その値は false になります。この場合は、addressComplete プロパティが存在するかどうかを判定するか、プロパティを直接クエリする必要があります。例については、下記の住所の品質をご覧ください。

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

住所の品質

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

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

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

次のアクションの候補

このプロダクトまたは機能は、pre-GA（一般提供前）のプレビュー版です。 pre-GA のプロダクトや機能では、サポートが限定されることがあります。また、pre-GA のプロダクトや機能を変更すると、他の pre-GA バージョンに対応しなくなる場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳しくは、 リリース ステージ の説明をご覧ください。

possibleNextAction 判定フィールドは、API レスポンスの解釈の概要を示します。これは、 取るべき次のアクションを判断するのに役立ちます。このフィールドは API レスポンスの他のフィールドから派生したものであり、住所の正確性や配達可能性を保証するものではありません。

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

キーポイント: address プロパティを使用して、住所の書式設定を取得します。サブコンポーネント addressComponent を使用して、エラーを調査し、そのエラーに関する情報を顧客に提供します。ただし、住所コンポーネントの特定の確認レベルに依存するように統合を構築しないでください。統合のガイダンスについては、検証ロジックを構築するをご覧ください。

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

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

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

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

geocode プロパティ

**キーポイント:** ロジックで Geocoding API を呼び出した場合は、geocode プロパティを使用してジオコードまたは プレイス ID を取得すると便利です。

geocode プロパティは、入力住所に関連付けられたジオコードの位置を示します。このプロパティは、プレイス ID など、位置自体の詳細を提供します。

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

metadata プロパティ

キーポイント: metadata プロパティを使用して、住所に関連付けられたプロパティのタイプ（住宅、私書箱、ビジネス）を判断します。

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

Address Validation API の適用範囲とAddress metadataのリファレンスをご覧ください。

uspsData プロパティ

**キーポイント:** uspsData プロパティを使用して、米国の住所に関する配達の信頼度レベルや その他の USPS の詳細情報を取得します。

このプロパティは、米国の住所に関する有用な情報を提供します。 ただし、このサービスで検証されたすべての住所に完全に設定されるとは限りません。そのため、このプロパティを住所の検証の唯一の手段として使用するのではなく、verdict と address も確認する必要があります。

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