- HTTP リクエスト
- リクエストの本文
- レスポンスの本文
- PostalAddress
- LanguageOptions
- ValidationResult
- 判定結果
- 粒度
- 住所
- 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 は、 |
previousResponseId |
最初の住所検証リクエストでは、このフィールドを空にする必要があります。1 つの住所を完全に検証するためにさらにリクエストが必要な場合(たとえば、最初の検証後にユーザーが行った変更を再検証する必要がある場合)、フォローアップ リクエストでは、検証シーケンスの最初のレスポンスの |
enableUspsCass |
USPS CASS 互換モードを有効にします。これは コンポーネント化された |
languageOptions |
省略可。プレビュー: この機能はプレビュー版(pre-GA)です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。 Address Validation API がレスポンスに追加情報を含めることを有効にします。 |
sessionToken |
省略可。オートコンプリート セッションを課金目的で識別する文字列。長さが 36 文字以下の ASCII 文字の、URL とファイル名に安全な base64 文字列にする必要があります。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。 セッションは、ユーザーがオートコンプリート クエリを実行すると開始され、場所を選択して Place Details または Address Validation が呼び出されると終了します。各セッションでは、複数の Autocomplete クエリの後に 1 つの Place Details または Address Validation リクエストが続きます。セッション内の各リクエストに使用される認証情報は、同じ Google Cloud コンソール プロジェクトに属している必要があります。セッションが終了するとトークンは無効になります。アプリでセッションごとに新しいトークンを生成する必要があります。 注: Address Validation は Autocomplete (New) API のセッションでのみ使用できます。Autocomplete API では使用できません。詳しくは、https://developers.google.com/maps/documentation/places/web-service/session-pricing をご覧ください。 |
レスポンスの本文
住所検証リクエストに対するレスポンス。
成功すると、レスポンスの本文に次の構造のデータが含まれます。
JSON 表現 |
---|
{
"result": {
object ( |
フィールド | |
---|---|
result |
住所検証の結果。 |
responseId |
このレスポンスを識別する 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 |
|
regionCode |
省略可。住所の国 / 地域に対応する CLDR 地域コード。詳しくは、https://cldr.unicode.org/ と https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html をご覧ください。(例: スイスの場合は「CH」)。地域コードが指定されていない場合は、住所から推定されます。最適なパフォーマンスを得るには、わかっている場合は地域コードを含めることをおすすめします。リージョンが一致しない場合や繰り返されていると、パフォーマンスが低下する可能性があります。たとえば、 |
languageCode |
入力住所の言語コードは将来の使用のために予約されており、現在は無視されます。API は、住所がある場所の適切な言語で住所を返します。 |
postalCode |
省略可。住所の郵便番号。国によっては郵便番号が使用されていない場合や、指定する必要がない場合もありますが、使用されている場合は住所の他の部分と組み合わせて追加の検証を行うことができます(例: 米国での州と郵便番号の検証)。 |
sortingCode |
省略可。国固有の付加的な並べ替えコード。ほとんどの地域では、これは使用されていません。使用されている場合、値は「CEDEX」のような文字列か(その後に数字を付加した「CEDEX 7」のような形式の場合もあります)、数字のみとなります。たとえば、ジャマイカの「セクターコード」、マラウイの「配達区域インジケーター」、コートジボワールの「郵便局インジケーター」などがこれに該当します。 |
administrativeArea |
省略可。その国 / 地域の郵便住所に使用される最上位の行政区域。たとえば、州、省、都道府県などがこれに該当します。特にスペインでは、これは自治州ではなく県になります(例: 「カタルーニャ」ではなく「バルセロナ」)。州や県などの行政区域が郵便住所に使用されない国もあります。たとえば、スイスではこの項目を空のままにします。 |
locality |
省略可。通常は住所の市区町村の部分を指します。たとえば、米国の市、イタリアのコムーネ、英国の郵便町名などがこれに該当します。地域区分が適切に定義されていないところや、この構造にうまく適合しない地域では、locality を空のままにして addressLines を使用してください。 |
sublocality |
省略可。住所の市区町村部分より下位の区分。たとえば、字、特別区、地区などがこれに該当します。 |
addressLines[] |
必須。構造化されていない住所の下位部分を記述する行。 |
recipients[] |
このフィールドは設定しないでください。現在、Address Validation API では使用されていません。現時点では、このフィールドが設定されたリクエストは API で拒否されませんが、情報は破棄され、レスポンスで返されません。 |
organization |
このフィールドは設定しないでください。現在、Address Validation API では使用されていません。現時点では、このフィールドが設定されたリクエストは API で拒否されませんが、情報は破棄され、レスポンスで返されません。 |
LanguageOptions
プレビュー: この機能はプレビュー版(pre-GA)です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。
Address Validation API がレスポンスに追加情報を含めることを有効にします。
JSON 表現 |
---|
{ "returnEnglishLatinAddress": boolean } |
フィールド | |
---|---|
returnEnglishLatinAddress |
プレビュー: 英語の |
ValidationResult
住所の検証結果。
JSON 表現 |
---|
{ "verdict": { object ( |
フィールド | |
---|---|
verdict |
全体の判定フラグ |
address |
ジオコードではなく、住所自体に関する情報。 |
geocode |
住所がジオコーディングされた場所と場所に関する情報。 |
metadata |
配送可能性に関するその他の情報。Address Validation API に送信されるすべての住所に対して、 |
uspsData |
USPS が提供する追加の配送フラグ。リージョン |
englishLatinAddress |
プレビュー: この機能はプレビュー版(pre-GA)です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform サービス固有の規約が適用されます。詳細については、リリース ステージの説明をご覧ください。 英語に翻訳された住所。 変換された住所を API 入力として再利用することはできません。サービスにより、ユーザーは最初に提供された住所の検証を母国語で確認または拒否できます。 住所の一部に英語の翻訳がない場合、サービスはラテン文字を使用した代替言語でその部分を返します。代替言語が選択される仕組みについては、こちらをご覧ください。住所の一部にラテン文字を使用する言語の翻訳や文字変換がない場合、サービスは住所に関連付けられたローカル言語でその部分を返します。 この出力を有効にするには、 注: |
判断
住所検証の結果とジオコードの概要。
JSON 表現 |
---|
{ "inputGranularity": enum ( |
フィールド | |
---|---|
inputGranularity |
入力アドレスの粒度。これは入力住所の解析結果であり、検証シグナルは得られません。検証シグナルについては、下記の たとえば、入力住所に特定のアパート番号が含まれている場合、ここでの |
validationGranularity |
API が住所を完全に検証できる粒度レベル。validateたとえば、 住所ごとのコンポーネントの検証結果は、 |
geocodeGranularity |
これは上記の |
addressComplete |
未解決のトークンや想定外の住所要素、欠落している住所がなければ、住所は完全とみなされます。設定されていない場合は、値が |
hasUnconfirmedComponents |
分類または検証ができない住所コンポーネントが 1 つ以上あります。詳しくは、 |
hasInferredComponents |
入力に含まれていない住所コンポーネントが推定(追加)されました。詳しくは、 |
hasReplacedComponents |
少なくとも 1 つの住所コンポーネントが置き換えられました。詳しくは、 |
粒度
住所またはジオコードに含まれるさまざまな粒度。これらの値は、住所の粒度を示すために使用される場合、住所が送付先を識別する粒度を示します。たとえば、「123 Main Street, Redwood City, CA, 94061」という住所は PREMISE
を識別し、「Redwood City, CA, 94061」などの住所は LOCALITY
を識別します。ただし、レッドウッド シティで「123 Main Street」のジオコードが見つからなかった場合、住所がより詳細であっても、返されるジオコーディングの粒度は LOCALITY
である可能性があります。
列挙型 | |
---|---|
GRANULARITY_UNSPECIFIED |
デフォルト値。この値は使用されません。 |
SUB_PREMISE |
アパートなど、建物より下のレベルの検索結果。 |
PREMISE |
建物レベルの検索結果。 |
PREMISE_PROXIMITY |
住所の建物レベルの位置を推定するジオコード。 |
BLOCK |
住所またはジオコードがブロックを表しています。ブロックレベルのアドレス指定があるリージョン(日本など)でのみ使用します。 |
ROUTE |
ジオコードまたは住所が、道路、道路、高速道路など、経路を細かく制御している。 |
OTHER |
その他のすべての粒度は、提供できないためまとめてバケットにまとめられます。 |
住所
後処理された住所の詳細。後処理には、住所のスペルミスのある箇所の修正、間違った箇所の置き換え、欠落している箇所の推測などが含まれます。
JSON 表現 |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
フィールド | |
---|---|
formattedAddress |
後処理された住所。住所がある地域の住所形式ルールに従って、1 行で表記されます。 |
postalAddress |
郵送先住所として表される、後処理された住所。 |
addressComponents[] |
順序なしリスト。フォーマットおよび修正された住所の個々の住所コンポーネントと、検証情報。個々のコンポーネントの検証ステータスに関する情報を確認できます。 住所コンポーネントの順序が異なるわけではありません。リスト内の住所コンポーネントの順序を前提にしないでください。 |
missingComponentTypes[] |
正しい形式の送付先住所に含まれているはずだったコンポーネントのタイプが、入力に含まれておらず、かつ推測できなかったもの。このタイプのコンポーネントは、 |
unconfirmedComponentTypes[] |
|
unresolvedTokens[] |
解決できなかった入力内のトークン。これは、住所の有効な部分として認識されなかった入力である可能性があります(たとえば、「123235253253 Main St, San Francisco, CA, 94105」のような入力では、未解決のトークンは |
AddressComponent
番地、市区町村、都道府県などの住所コンポーネントを表します。
JSON 表現 |
---|
{ "componentName": { object ( |
フィールド | |
---|---|
componentName |
このコンポーネントの名前。 |
componentType |
住所コンポーネントのタイプ。指定可能なタイプのリストについては、表 2: プレイス サービスで返されるその他のタイプをご覧ください。 |
confirmationLevel |
コンポーネントが正しいことに関する確実性のレベルを示します。 |
inferred |
コンポーネントは入力に含まれていませんが、住所の場所として推定され、完全な住所に対して提供されるべきだと判断されたことを示します。 |
spellCorrected |
コンポーネント名のスペルミスが修正されたことを示します。API は、「centre」を「center」に変更するなどして、あるスペルのバリアントから別のスペルに変更された場合に必ず報告するわけではありません。また、「Amphitheater Pkwy」を「Amphitheatre Pkwy」に変更するなど、一般的なスペルミスが報告されない場合もあります。 |
replaced |
コンポーネントの名前がまったく別の名前に置き換えられたことを示します。たとえば、間違った郵便番号が住所に対して正しい名前に置き換えられた場合などです。これは外観上の変更ではなく、入力コンポーネントが別のコンポーネントに変更されました。 |
unexpected |
指定された地域の郵便の宛先には含まれないはずの住所コンポーネントを示します。これは、入力の一部であったという理由だけで保持しています。 |
ComponentName
コンポーネント名のラッパー。
JSON 表現 |
---|
{ "text": string, "languageCode": string } |
フィールド | |
---|---|
text |
名前のテキスト。たとえば、道路名の場合は「5th Avenue」、番地の場合は「1253」です。 |
languageCode |
BCP-47 言語コード。コンポーネント名が言語(番地など)に関連付けられていない場合、この属性は存在しません。 |
ConfirmationLevel
確認レベルのさまざまな値。
列挙型 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
デフォルト値。この値は使用されません。 |
CONFIRMED |
Google は、この要素が存在し、住所の残りの部分のコンテキストで意味をなすことを確認しました。 |
UNCONFIRMED_BUT_PLAUSIBLE |
このコンポーネントは確認できませんでしたが、存在している可能性があります。たとえば、番地が不明な、道路上の有効な番号範囲の番地など。 |
UNCONFIRMED_AND_SUSPICIOUS |
このコンポーネントは確認されていないため、間違っている可能性があります。(例: 住所の残りの部分に一致しない地区)。 |
ジオコード
入力がジオコーディングされた場所に関する情報が含まれます。
JSON 表現 |
---|
{ "location": { object ( |
フィールド | |
---|---|
location |
入力のジオコーディングされた場所。 住所、緯度と経度の座標、Plus Code よりもプレイス ID の使用をおすすめします。ルート選択や運転ルートの計算で座標を使用すると、ポイントは常にその座標に最も近い道路にスナップされます。目的地に迅速かつ安全につながる道路ではないこと、宿泊施設への出入り口付近でないことも考えられます。また、ビジネス情報をリバース ジオコーディングする場合、返される住所が元の住所と一致する保証はありません。 |
plusCode |
|
bounds |
ジオコーディングされた場所の境界。 |
featureSizeMeters |
ジオコーディングされた場所のサイズ(メートル単位)。これはジオコーディングされた場所の粗さを示すもう一つの尺度ですが、セマンティックな意味というよりも物理的なサイズで表します。 |
placeId |
この入力によってジオコーディングされる場所の PlaceID。 プレイス ID について詳しくは、こちらをご覧ください。 |
placeTypes[] |
入力がジオコーディングされた場所のタイプ(複数可)。たとえば、 |
LatLng
緯度と経度のペアを表すオブジェクト。緯度を表す倍精度値と経度を表す倍精度値のペアで表現されます。特に指定のない限り、このオブジェクトは WGS84 規格に準拠する必要があります。値は正規化範囲内で指定する必要があります。
JSON 表現 |
---|
{ "latitude": number, "longitude": number } |
フィールド | |
---|---|
latitude |
緯度(度単位)。範囲 [-90.0, +90.0] 内になければなりません。 |
longitude |
経度(度単位)。範囲 [-180.0, +180.0] 内になければなりません。 |
PlusCode
Plus Code(http://plus.codes)は、14 mx14 m(1/8,000 度)以下の長方形を定義するグローバル コードと、プレフィックスをリファレンスの場所に置き換える複合コードの 2 つの形式のロケーション参照です。
JSON 表現 |
---|
{ "globalCode": string, "compoundCode": string } |
フィールド | |
---|---|
globalCode |
場所のグローバル(完全)コード。たとえば「9FWM33GV+HQ」は、1/8, 000 x 1/8,000 度の領域(約 14 x 14 メートル)を表します。 |
compoundCode |
場所の複合コードで、「33GV+HQ, Ramberg, Norway」など。グローバル コードの接尾辞を含み、接頭辞は参照エンティティのフォーマットされた名前に置き換えます。 |
ビューポート
low
と high
の対角線上の 2 つのポイントとして表される緯度と経度のビューポート。ビューポートは閉じられた領域と見なされます。つまり、その境界線も含まれます。緯度の範囲は -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 |
ビジネスの住所であることを示します。設定されていない場合は、値が不明であることを示します。 |
poBox |
私書箱の住所を示します。設定されていない場合は、値が不明であることを示します。 |
residential |
居住地の住所であることを示します。設定されていない場合は、値が不明であることを示します。 |
UspsData
住所の USPS データ。Address Validation API に送信されるすべての米国または PR の住所で uspsData
が完全に入力されるとは限りません。レスポンスのメインの部分として uspsData を使用する場合は、バックアップ アドレス フィールドをレスポンスに統合することをおすすめします。
JSON 表現 |
---|
{
"standardizedAddress": {
object ( |
フィールド | |
---|---|
standardizedAddress |
USPS 標準住所。 |
deliveryPointCode |
2 桁の配送先コード |
deliveryPointCheckDigit |
配送先のチェック ディジット。機械的にスキャンされたメールの場合は、この番号が delivery_point_barcode の末尾に追加されます。Delivery_point_barcode、deliveryPointCheckDigit、postal code、ZIP+4 のすべての桁を合計すると、10 で割り切れる数値になります。 |
dpvConfirmation |
DPV 確認に使用できる値。1 文字を返すか、値を返しません。
|
dpvFootnote |
配送ポイントの検証の脚注複数の脚注を同じ文字列にまとめることができます。
|
dpvCmra |
住所が CMRA(商業郵便受取所)かどうか、つまり顧客の郵便物を受け取る民間企業かどうかを示します。1 文字を返します。
|
dpvVacant |
空いている場所ですか?1 文字を返します。
|
dpvNoStat |
これは統計データのない住所ですか、それとも有効な住所ですか?統計情報がない住所とは、継続的に占有されていない住所や、USPS がサービスを提供していない住所です。1 文字を返します。
|
dpvNoStatReasonCode |
NoStat のタイプを示します。理由コードを int として返します。
|
dpvDrop |
フラグは、サイトの単一の受信可能にメールが配信されることを示します。1 文字を返します。
|
dpvThrowback |
郵便物が番地に配送されないことを示します。1 文字を返します。
|
dpvNonDeliveryDays |
メールの配信が毎日行われていないことを示すフラグ。1 文字を返します。
|
dpvNonDeliveryDaysValues |
配達不能の日数を識別する整数。次のビットフラグを使用して照会できます。0x40 – 日曜日が配達不能の日 0x20 – 月曜日が配達不能の日 0x10 – 火曜日が配達不能の日 0x08 – 水曜日が配達不能の日 0x04 – 木曜日が配達不能の日 0x02 – 金曜日が配達不能 – 土曜日が配達不能の日 0x01 |
dpvNoSecureLocation |
フラグはドアにアクセス可能であるが、セキュリティ上の懸念により荷物が置かれないことを示しています。1 文字を返します。
|
dpvPbsa |
アドレスが PBSA レコードと一致したことを示します。1 文字を返します。
|
dpvDoorNotAccessible |
フラグは、USPS がドアをノックして郵便物を配送できない住所を示します。1 文字を返します。
|
dpvEnhancedDeliveryCode |
このアドレスに対して複数の DPV 戻りコードが有効になっていることを示します。1 文字を返します。
|
carrierRoute |
運送業者のルートコード。1 文字の接頭辞と 3 桁の経路指定子からなる 4 文字のコード。 接頭辞:
|
carrierRouteIndicator |
運送業者のルートの送料の並べ替えインジケーター。 |
ewsNoMatch |
配送先住所は照合可能ですが、EWS ファイルには完全一致がまもなく利用可能になる旨が記載されています。 |
postOfficeCity |
主な郵便局の市区町村。 |
postOfficeState |
メインの郵便局の州。 |
abbreviatedCity |
略称の都市。 |
fipsCountyCode |
FIPS 郡コード。 |
county |
郡名。 |
elotNumber |
拡張旅程(eLOT)番号。 |
elotFlag |
eLOT 昇順/降順フラグ(A/D)。 |
lacsLinkReturnCode |
LACSLink 戻りコード。 |
lacsLinkIndicator |
LACSLink インジケーター。 |
poBoxOnlyPostalCode |
私書箱のみの郵便番号。 |
suitelinkFootnote |
道路や高層ビルのレコードから部屋の情報にマッチした脚注。ビジネス名が一致する場合、予備の番号が返されます。
|
pmbDesignator |
PMB(私用メールボックス)の単位指定子。 |
pmbNumber |
PMB(私書箱)番号 |
addressRecordType |
入力住所に一致する住所レコードのタイプ。
|
defaultAddress |
デフォルトの住所が見つかったものの、より具体的な住所が存在することを示すインジケーター。 |
errorMessage |
USPS データの取得に関するエラー メッセージ。人為的に作成された住所が検出されたために USPS の処理が一時停止された場合に入力されます。 このエラーが表示されると、USPS データ フィールドにデータが入力されないことがあります。 |
cassProcessed |
リクエストが CASS 処理されたことを示すインジケーター。 |
UspsAddress
米国の住所の USPS 表現。
JSON 表現 |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
フィールド | |
---|---|
firstAddressLine |
住所 1 行目。 |
firm |
企業名 |
secondAddressLine |
住所の 2 行目。 |
urbanization |
プエルトリコの都市化の名前。 |
cityStateZipAddressLine |
市区町村 + 都道府県 + 郵便番号。 |
city |
市町村名。 |
state |
2 文字の州コード。 |
zipCode |
郵便番号(例: 10009)。 |
zipCodeExtension |
4 桁の郵便番号の拡張コード(例: 5023)。 |