- HTTP リクエスト
- リクエストの本文
- レスポンスの本文
- PostalAddress
- LanguageOptions
- ValidationResult
- Verdict
- 粒度
- 住所
- AddressComponent
- ComponentName
- ConfirmationLevel
- ジオコード
- LatLng
- PlusCode
- ビューポート
- AddressMetadata
- UspsData
- UspsAddress
住所を検証します。
HTTP リクエスト
POST https://addressvalidation.googleapis.com/v1:validateAddress
この URL は gRPC Transcoding 構文を使用します。
リクエストの本文
リクエストの本文には、次の構造のデータが含まれます。
JSON 表現 |
---|
{ "address": { object ( |
フィールド | |
---|---|
address |
必須。住所の確認中。フォーマットされていない住所は この入力のフィールドの合計長は 280 文字以内にする必要があります。 サポートされているリージョンについては、こちらをご覧ください。 入力アドレスの Address Validation API は、 |
previous |
最初の住所検証リクエストでは、このフィールドは空にする必要があります。1 つの住所を完全に検証するためにさらにリクエストが必要な場合(たとえば、ユーザーが最初の検証後に行った変更を再検証する必要がある場合など)、各フォローアップ リクエストで、検証シーケンスの最初のレスポンスの |
enable |
USPS CASS 互換モードを有効にします。これは コンポーネント化された |
language |
省略可。プレビュー版: この機能はプレビュー版(pre-GA)です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。 Address Validation API がレスポンスに追加情報を含めることができるようにします。 |
session |
省略可。請求目的で Autocomplete セッションを識別する文字列。URL とファイル名に安全な base64 文字列で、ASCII 文字で 36 文字以内にする必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。 セッションは、ユーザーが Autocomplete クエリを実行したときに開始され、ユーザーが場所を選択し、Place Details または Address Validation が呼び出されると終了します。セッションによっては、複数のオートコンプリート クエリが入力された後に、1 つの Place Details リクエストまたは Address Validation リクエストが実行される場合もあります。セッション内の各リクエストに使用する認証情報は、同じ Google Cloud コンソール プロジェクトに属している必要があります。セッションが終了すると、トークンは無効になります。アプリでは、セッションごとに新しいトークンを生成する必要があります。 注: Address Validation は、Autocomplete API ではなく、Autocomplete(新規)API を使用するセッションでのみ使用できます。詳しくは、https://developers.google.com/maps/documentation/places/web-service/session-pricing をご覧ください。 |
レスポンスの本文
住所確認リクエストに対するレスポンス。
成功した場合、レスポンスの本文には次の構造のデータが含まれます。
JSON 表現 |
---|
{
"result": {
object ( |
フィールド | |
---|---|
result |
住所確認の結果。 |
response |
このレスポンスを識別する UUID。住所の再確認が必要な場合は、この UUID を新しいリクエストに含める必要があります。 |
PostalAddress
郵便の配達先や支払場所などに使用される住所を表します。郵便住所がわかっていれば、郵便サービスによって住宅や私書箱などに商品を配達できます。これは地理的な場所(道路、町、山)を指し示すものではありません。
通常の用途では、住所はユーザーによる入力か既存データのインポートによって作成されます(プロセスの種類によります)。
住所の入力または編集に関するアドバイス: - 国際化対応の住所ウィジェット(https://github.com/google/libaddressinput など)を使用してください。- フィールドの入力または編集に使用する UI 要素は、そのフィールドが使用されない国ではユーザーに表示しないでください。
このスキーマの使用方法の詳細については、https://support.google.com/business/answer/6397478 をご覧ください。
JSON 表現 |
---|
{ "revision": integer, "regionCode": string, "languageCode": string, "postalCode": string, "sortingCode": string, "administrativeArea": string, "locality": string, "sublocality": string, "addressLines": [ string ], "recipients": [ string ], "organization": string } |
フィールド | |
---|---|
revision |
|
region |
省略可。住所の国 / 地域に対応する CLDR 地域コード。詳しくは、https://cldr.unicode.org/ と https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html をご覧ください。例: スイスの場合は「CH」です。地域コードが指定されていない場合は、住所から推測されます。最適なパフォーマンスを得るには、地域コードがわかっている場合はそのコードを含めることをおすすめします。リージョンが不整合または重複していると、パフォーマンスが低下する可能性があります。たとえば、 |
language |
入力アドレスの言語コードは将来の使用のために予約されており、現在は無視されます。API は、住所が存在する地域に適した言語で住所を返します。 |
postal |
省略可。住所の郵便番号。すべての国で郵便番号の使用や存在を必要としているわけではありませんが、使用されている場合は、住所の他の部分で追加の確認が行われることがあります(例: 米国での州 / 郵便番号の確認)。 |
sorting |
省略可。追加の国固有の並べ替えコード。ほとんどの地域では、これは使用されていません。使用される場合、値は「CEDEX」のような文字列で、その後に必要に応じて数字を付けたもの(例: 「CEDEX 7」)や、数字だけのものがあります。たとえば、ジャマイカの「セクターコード」、マラウイの「配達区域インジケータ」、コートジボワールの「郵便局インジケータ」などです。 |
administrative |
省略可。その国 / 地域の住所に使用される最上位の行政区域。たとえば、州、省、都道府県などがこれに該当します。特にスペインでは、これは自治州ではなく県になります(例: 「カタルーニャ」ではなく「バルセロナ」)。州や県などの行政区画が住所表記に使用されない国もあります。たとえば、スイスではこの項目を空のままにします。 |
locality |
省略可。通常は住所の市区町村の部分を指します。たとえば、米国の市、イタリアのコムーネ、英国の郵便町名などがこれに該当します。地域区分が適切に定義されていないところや、この構造にうまく適合しない地域では、locality を空のままにして addressLines を使用してください。 |
sublocality |
省略可。住所の市町村部分の下位の区画。たとえば、字、特別区、地区などがこれに該当します。 |
address |
必須。住所の下位部分を記述する非構造化の住所行。 |
recipients[] |
このフィールドは設定しないでください。現在、Address Validation API では使用されていません。現時点では、このフィールドが設定されたリクエストは拒否されませんが、情報は破棄され、レスポンスで返されることはありません。 |
organization |
このフィールドは設定しないでください。Address Validation API では現在使用されていません。現時点では、このフィールドが設定されたリクエストは拒否されませんが、情報は破棄され、レスポンスで返されることはありません。 |
LanguageOptions
プレビュー: この機能は、pre-GA(一般提供前)のプレビュー版です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。
レスポンスに追加の情報を含めるために Address Validation API を有効にします。
JSON 表現 |
---|
{ "returnEnglishLatinAddress": boolean } |
フィールド | |
---|---|
return |
プレビュー: 英語で |
ValidationResult
住所の検証結果。
JSON 表現 |
---|
{ "verdict": { object ( |
フィールド | |
---|---|
verdict |
総合判定フラグ |
address |
ジオコードではなく、住所自体に関する情報。 |
geocode |
住所がジオコーディングされた場所と場所に関する情報。 |
metadata |
成果物に関するその他の情報。 |
usps |
USPS が提供する配送に関する追加フラグ。リージョン |
english |
プレビュー: この機能は、pre-GA(一般提供前)のプレビュー版です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。 英語に翻訳された住所。 変換された住所は、API 入力として再利用できません。ユーザーが母国語で、最初に提供した住所の検証を確認または拒否できるように、このサービスが提供されています。 住所の一部に英語の翻訳がない場合は、その部分はラテン文字を使用する代替言語で返されます。代替言語の選択方法については、こちらをご覧ください。住所の一部にラテン文字を使用する言語の翻訳や訳文がない場合は、住所に関連付けられたローカル言語でその部分が返されます。 この出力を有効にするには、 注: |
判断
住所の検証結果とジオコードの概要。
JSON 表現 |
---|
{ "inputGranularity": enum ( |
フィールド | |
---|---|
input |
入力アドレスの粒度。これは入力アドレスの解析結果であり、検証シグナルは提供されません。検証シグナルについては、下記の たとえば、入力アドレスに特定の部屋番号が含まれている場合、ここでの |
validation |
API が住所を完全に検証できる粒度レベル。たとえば、 住所の構成要素ごとの検証結果は |
geocode |
これは、上記の |
address |
未解決のトークンがなく、予期しない住所コンポーネントや不足している住所コンポーネントがない場合、住所は完全と見なされます。未設定の場合、値は |
has |
分類または検証できない住所コンポーネントが 1 つ以上あります。詳しくは、 |
has |
入力に含まれていない住所の要素が 1 つ以上推定(追加)されました。詳しくは、 |
has |
少なくとも 1 つの住所コンポーネントが置き換えられました。詳しくは、 |
粒度
住所またはジオコードにおける、さまざまな粒度。住所の粒度を示すために使用される場合、これらの値は、住所が送付先をどの程度細かく識別するかを示します。たとえば、「123 Main Street, Redwood City, CA, 94061」のような住所は PREMISE
を識別し、「Redwood City, CA, 94061」のような住所は LOCALITY
を識別します。ただし、Redwood City の「123 Main Street」のジオコードが見つからない場合は、住所の精度がそれよりも高いにもかかわらず、返されるジオコードの精度が LOCALITY
になることがあります。
列挙型 | |
---|---|
GRANULARITY_UNSPECIFIED |
デフォルト値。この値は使用されません。 |
SUB_PREMISE |
アパートなどの建物より下の階の検索結果。 |
PREMISE |
建物レベルの結果。 |
PREMISE_PROXIMITY |
住所の建物レベルの位置を近似したジオコード。 |
BLOCK |
住所またはジオコードはブロックを示します。ブロックレベルのアドレス指定が使用されている地域(日本など)でのみ使用されます。 |
ROUTE |
ジオコードまたは住所が道路(街路、道路、高速道路など)単位で指定されている。 |
OTHER |
その他のすべての粒度。配信できないため、まとめてバケット化されます。 |
住所
処理後の住所の詳細。後処理には、住所のスペルミスの修正、誤った部分の置き換え、不足している部分の推定が含まれます。
JSON 表現 |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
フィールド | |
---|---|
formatted |
住所が存在する地域の住所形式ルールに従って、1 行の住所としてフォーマットされた、後処理済みの住所。 注: この住所の形式は、 |
postal |
住所として表された、後処理済みの住所。 |
address |
順序なしリスト。形式が整えられて修正された住所の個々の住所構成要素と、検証情報。これにより、個々のコンポーネントの検証ステータスに関する情報が提供されます。 住所コンポーネントは特定の順序で並べられていません。リスト内の住所コンポーネントの順序については想定しないでください。 |
missing |
正しい形式の郵送先住所に存在することが想定されるが、入力に見つからず、推測もできないコンポーネントのタイプ。このタイプのコンポーネントは、 |
unconfirmed |
|
unresolved |
解決できなかった入力内のトークン。住所の有効な部分として認識されなかった入力である可能性があります。たとえば、「Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US」のような入力の場合、未解決のトークンは |
AddressComponent
番地、市区町村、都道府県(州)などの住所の構成要素を表します。
JSON 表現 |
---|
{ "componentName": { object ( |
フィールド | |
---|---|
component |
このコンポーネントの名前。 |
component |
住所コンポーネントのタイプ。使用可能なタイプのリストについては、表 2: プレイス サービスで返されるその他のタイプをご覧ください。 |
confirmation |
コンポーネントが正しいことの確信度を示します。 |
inferred |
このコンポーネントは入力の一部ではありませんでしたが、住所の場所から推測され、完全な住所として提供される必要があると判断されました。 |
spell |
コンポーネント名のスペルミスの修正を示します。API は、スペルのバリエーションの変更を常に報告するわけではありません(「centre」を「center」に変更した場合など)。また、「Amphitheater Pkwy」を「Amphitheatre Pkwy」に変更するなど、よくあるスペルミスが常に報告されるわけではありません。 |
replaced |
コンポーネントの名前が完全に異なる名前に置き換えられたことを意味します。たとえば、間違った郵便番号が住所に対応する正しい郵便番号に置き換えられたことを意味します。これは外観の変更ではなく、入力コンポーネントが別のコンポーネントに変更されています。 |
unexpected |
指定された地域の郵便住所に存在しないことが想定される住所構成要素を示します。入力の一部であるためのみ保持しています。 |
ComponentName
コンポーネント名のラッパー。
JSON 表現 |
---|
{ "text": string, "languageCode": string } |
フィールド | |
---|---|
text |
名前のテキスト。たとえば、通り名の場合は「5th Avenue」、番地の場合は「1253」と入力します。 |
language |
BCP-47 言語コード。コンポーネント名が言語(番地など)と関連付けられていない場合、このフィールドはありません。 |
ConfirmationLevel
確認レベルに指定できる値。
列挙型 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
デフォルト値。この値は使用されません。 |
CONFIRMED |
このコンポーネントが存在し、住所の他の部分のコンテキストで妥当であることを確認できました。 |
UNCONFIRMED_BUT_PLAUSIBLE |
このコンポーネントは確認できませんでしたが、存在する可能性はあります。例: 特定の番地が不明な道路上で、既知の有効な範囲内の番地。 |
UNCONFIRMED_AND_SUSPICIOUS |
このコンポーネントは確認されていないため、誤っている可能性があります。たとえば、住所の残りの部分と一致しない地域などです。 |
ジオコード
入力がジオコーディングされた場所に関する情報が含まれます。
JSON 表現 |
---|
{ "location": { object ( |
フィールド | |
---|---|
location |
入力のジオコーディングされた位置。 プレイス ID は、住所、緯度と経度の座標、Plus Code よりも使用することをおすすめします。運転ルートのルーティングや計算を行う際に座標を使用すると、その座標に最も近い道路にポイントがスナップされます。目的地に迅速かつ安全に到達できる道路ではない可能性があります。また、物件へのアクセス ポイントの近くにないこともあります。また、場所がリバース ジオコーディングされた場合、返される住所が元の住所と一致する保証はありません。 |
plus |
|
bounds |
ジオコーディングされた場所の境界。 |
feature |
ジオコーディングされた場所のサイズ(メートル単位)。これは、ジオコーディングされた位置情報の粗さを表すもう 1 つの指標ですが、意味的な意味ではなく物理的なサイズで表されます。 |
place |
この入力がジオコーディングされる場所の PlaceID。 プレイス ID の詳細については、こちらをご覧ください。 |
place |
入力がジオコーディングされた場所のタイプ。たとえば、 |
LatLng
緯度と経度のペアを表すオブジェクト。これは緯度を表す倍精度値と経度を表す倍精度値のペアで表現されます。特に明記されていない場合、このオブジェクトは WGS84 規格に準拠する必要があります。値は正規化範囲内で指定する必要があります。
JSON 表現 |
---|
{ "latitude": number, "longitude": number } |
フィールド | |
---|---|
latitude |
緯度(度単位)。範囲 [-90.0, +90.0] 内になければなりません。 |
longitude |
経度(度単位)。範囲 [-180.0, +180.0] 内になければなりません。 |
PlusCode
Plus Code(http://plus.codes)は、2 つの形式の場所の参照情報です。14 m x 14 m(8000 分の 1)以下の長方形を定義するグローバル コードと、プレフィックスを参照地に置き換えた複合コードです。
JSON 表現 |
---|
{ "globalCode": string, "compoundCode": string } |
フィールド | |
---|---|
global |
場所のグローバル(完全)コード(「9FWM33GV+HQ」など)。8000 分の 1 x 8000 分の 1 度(約 14 x 14 メートル)のエリアを表します。 |
compound |
場所の複合コード(「33GV+HQ, Ramberg, Norway」など)。グローバル コードの接尾辞が含まれ、接頭辞は参照エンティティの形式付きの名前に置き換えられています。 |
ビューポート
緯度と経度のビューポート。対角線上の 2 つの low
ポイントと high
ポイントで表されます。ビューポートは閉じた領域と見なされます。つまり、境界が含まれます。緯度の範囲は -90~90 度、経度の範囲は -180~180 度の範囲内で指定する必要があります。さまざまなケースには次のようなものがあります。
low
=high
の場合、ビューポートはその単一点で構成されます。low.longitude
>high.longitude
の場合、経度の範囲は反転します(ビューポートは 180 度の経度線と交差します)。low.longitude
= -180 度、high.longitude
= 180 度の場合、ビューポートにはすべての経度が含まれます。low.longitude
= 180 度、high.longitude
= -180 度の場合、経度の範囲は空になります。low.latitude
>high.latitude
の場合、緯度範囲は空になります。
low
と high
の両方に値を入力する必要があります。また、(上記の定義で指定されているように)表されるボックスを空にすることはできません。ビューポートが空の場合、エラーが発生します。
たとえば、このビューポートはニューヨーク市を完全に囲んでいます。
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
JSON 表現 |
---|
{ "low": { object ( |
フィールド | |
---|---|
low |
必須。ビューポートの低い部分。 |
high |
必須。ビューポートの高さ。 |
AddressMetadata
アドレスのメタデータ。Address Validation API に送信されるすべての住所について、metadata
が完全に入力される保証はありません。
JSON 表現 |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
フィールド | |
---|---|
business |
ビジネスの住所であることを示します。未設定の場合、値が不明であることを示します。 |
po |
私書箱の住所を示します。未設定の場合、値が不明であることを示します。 |
residential |
居住地の住所であることを示します。未設定の場合、値が不明であることを示します。 |
UspsData
住所の USPS データ。Address Validation API に送信された米国またはプエルトリコの住所について、uspsData
が完全に入力される保証はありません。uspsData をレスポンスの主な部分として使用する場合は、レスポンスにバックアップ アドレス フィールドを統合することをおすすめします。
JSON 表現 |
---|
{
"standardizedAddress": {
object ( |
フィールド | |
---|---|
standardized |
USPS の標準化された住所。 |
delivery |
2 桁の配送所コード |
delivery |
配送ポイントのチェック ディジット。この番号は、機械的にスキャンされた郵便物の delivery_point_barcode の末尾に追加されます。delivery_point_barcode、deliveryPointCheckDigit、郵便番号、ZIP+4 のすべての桁を加算すると、10 で割り切れる数になります。 |
dpv |
DPV 確認の有効な値。単一の文字を返すか、値を返しません。
|
dpv |
配送ポイントの検証に関する脚注。複数の脚注を同じ文字列に連結できます。
|
dpv |
住所が CMRA(商業郵便受取業者)であるかどうかを示します。CMRA とは、クライアントの郵便物を受け取る民間企業です。1 文字を返します。
|
dpv |
この場所は空いていますか?1 文字を返します。
|
dpv |
統計情報なしの住所ですか?それとも有効な住所ですか?統計住所は、継続的に居住していない住所や、USPS がサービスを提供していない住所ではありません。1 文字を返します。
|
dpv |
NoStat タイプを示します。理由コードを整数として返します。
|
dpv |
1 つのサイト内の 1 つの受信トレイに郵便物が配達されることを示すフラグ。1 文字を返します。
|
dpv |
郵便物が住所に発送されないことを示します。1 文字を返します。
|
dpv |
郵便配達が毎日行われないことを示すフラグ。1 文字を返します。
|
dpv |
配達が行われない日を識別する整数。ビットフラグを使用して照会できます。0x40 - 日曜日は配達日ではありません。0x20 - 月曜日は配達日ではありません。0x10 - 火曜日は配達日ではありません。0x08 - 水曜日は配達日ではありません。0x04 - 木曜日は配達日ではありません。0x02 - 金曜日は配達日ではありません。0x01 - 土曜日は配達日ではありません。 |
dpv |
フラグはドアがアクセス可能であるものの、セキュリティ上の理由から荷物を置いたままにしないことを示します。1 文字を返します。
|
dpv |
アドレスが PBSA レコードと一致したことを示します。1 文字を返します。
|
dpv |
USPS がドアをノックして郵便物を配達できない住所を示すフラグ。1 文字を返します。
|
dpv |
住所に対して複数の DPV 戻りコードが有効であることを示します。1 文字を返します。
|
carrier |
運送業者の経路コード。1 文字の接頭辞と 3 桁のルート指定子で構成される 4 文字のコード。 接頭辞:
|
carrier |
運送会社のルート料金の並べ替えインジケーター。 |
ews |
配送先住所は一致しますが、EWS ファイルには、完全一致がまもなく利用可能になると記載されています。 |
post |
メインの郵便局がある都市。 |
post |
メインの郵便局の状態。 |
abbreviated |
市区町村の省略形。 |
fips |
FIPS 郡コード。 |
county |
郡名。 |
elot |
拡張ルート(eLOT)番号。 |
elot |
eLOT 昇順/降順フラグ(A/D)。 |
lacs |
LACSLink の戻りコード。 |
lacs |
LACSLink インジケータ |
po |
郵便番号(私書箱のみ)。 |
suitelink |
ストリートまたは高層ビルのレコードとスイート情報の照合による脚注。ビジネス名が一致すると、2 番目の電話番号が返されます。
|
pmb |
PMB(Private Mail Box)ユニット指定子。 |
pmb |
PMB(私書箱)番号 |
address |
入力された住所と一致する住所レコードのタイプ。
|
default |
デフォルトの住所が見つかったものの、より具体的な住所が存在することを示すインジケーター。 |
error |
USPS データ取得に関するエラー メッセージ。人為的に作成された住所が検出されたために USPS の処理が停止された場合に入力されます。 このエラーが発生すると、USPS データ フィールドにデータが入力されないことがあります。 |
cass |
リクエストが CASS で処理されたことを示すインジケーター。 |
UspsAddress
米国の住所の USPS 表現。
JSON 表現 |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
フィールド | |
---|---|
first |
住所の 1 行目。 |
firm |
会社名。 |
second |
住所の 2 行目。 |
urbanization |
プエルトリコの都市化の名前。 |
city |
市区町村 + 都道府県 + 郵便番号 |
city |
市町村名。 |
state |
2 文字の州コード。 |
zip |
郵便番号(例: 10009)。 |
zip |
4 桁の郵便番号拡張コード(例: 5023)。 |