- 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 Service Specific Terms が適用されます。詳細については、リリース ステージの説明をご覧ください。 Address Validation API がレスポンスに追加情報を含めることを有効にします。 |
レスポンスの本文
住所検証リクエストへのレスポンス。
成功すると、レスポンスの本文に次の構造のデータが含まれます。
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 Service Specific Terms が適用されます。詳細については、リリース ステージの説明をご覧ください。
Address Validation API がレスポンスに追加情報を含めることを有効にします。
JSON 表現 |
---|
{ "returnEnglishLatinAddress": boolean } |
フィールド | |
---|---|
returnEnglishLatinAddress |
プレビュー: 英語の |
ValidationResult
住所の検証結果。
JSON 表現 |
---|
{ "verdict": { object ( |
フィールド | |
---|---|
verdict |
全体の判定フラグ |
address |
ジオコードではなく、住所そのものに関する情報。 |
geocode |
住所がジオコーディングされた場所と場所に関する情報。 |
metadata |
成果物に関連するその他の情報。 |
uspsData |
USPS から提供される追加の配送フラグ。 |
englishLatinAddress |
プレビュー: この機能はプレビュー版(pre-GA)です。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、一般提供前のプロダクトや機能の変更は、他の一般提供前のバージョンと互換性がない場合があります。pre-GA のサービスには、Google Maps Platform Service Specific Terms が適用されます。詳細については、リリース ステージの説明をご覧ください。 英語に翻訳された住所。住所に英語の翻訳がない場合、ラテン文字を使用した代替言語でその住所が返されます。代替言語の選択方法については、こちらをご覧ください。住所の一部にラテン文字を使用する言語の翻訳や文字変換がない場合、サービスは住所に関連付けられた現地言語でその部分を返します。 この出力を有効にするには、 注: |
判断
住所検証の結果とジオコードの概要。
JSON 表現 |
---|
{ "inputGranularity": enum ( |
フィールド | |
---|---|
inputGranularity |
入力アドレスの粒度。これは、入力された住所の解析結果であり、検証シグナルは得られません。検証シグナルについては、下記の たとえば、入力住所に特定のマンション番号が含まれている場合、 |
validationGranularity |
API で住所を完全に検証できる粒度。validateたとえば、 住所ごとのコンポーネントの検証結果は、 |
geocodeGranularity |
これは、上記の |
addressComplete |
未解決のトークンや、予期しない住所コンポーネント、欠落している住所コンポーネントがない場合、住所は完全とみなされます。詳しくは、 |
hasUnconfirmedComponents |
分類または検証ができない住所コンポーネントが 1 つ以上あります。詳しくは、 |
hasInferredComponents |
入力に含まれていない住所コンポーネントが 1 つ以上推定(追加)されました。詳しくは、 |
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 |
その他の粒度は提供できないため、1 つにまとめられます。 |
住所
後処理された住所の詳細。後処理には、住所のスペルミスのある部分の修正、誤った部分の置き換え、欠落している部分の推測が含まれます。
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 |
このコンポーネントが存在し、住所の残りの部分のコンテキストで意味をなしていることを確認できました。 |
UNCONFIRMED_BUT_PLAUSIBLE |
このコンポーネントは確認できませんでしたが、存在している可能性はあります。たとえば、具体的な番地が不明な道路上の番地(有効な範囲が既知の番地)など。 |
UNCONFIRMED_AND_SUSPICIOUS |
このコンポーネントは確認されていないため、誤っている可能性があります。(住所の後続部分と一致しない周辺地域など)。 |
ジオコード
入力がジオコーディングされた場所に関する情報が含まれます。
JSON 表現 |
---|
{ "location": { object ( |
フィールド | |
---|---|
location |
入力のジオコーディングされた場所。 住所、緯度と経度の座標、Plus Codes よりもプレイス 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 Codes(http://plus.codes)は、14mx14m(1/8,000 の度数)以下の長方形を定義するグローバル コードと、プレフィックスを参照の場所に置き換える複合コードという 2 つの形式を持つ場所の参照です。
JSON 表現 |
---|
{ "globalCode": string, "compoundCode": string } |
フィールド | |
---|---|
globalCode |
場所のグローバル(完全)コード。例: 1/8, 000 x 1/8,000 度の領域(14 x 14 m 以下)を表す「9FWM33GV+HQ」。 |
compoundCode |
場所の複合コード(「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
住所のメタデータ。metadata
では、Address Validation API に送信されたすべての住所が完全に入力されているとは限りません。
JSON 表現 |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
フィールド | |
---|---|
business |
ビジネスの住所であることを示します。設定されていない場合は、値が不明であることを示します。 |
poBox |
私書箱の住所を示します。設定されていない場合は、値が不明であることを示します。 |
residential |
住宅の住所であることを示します。設定されていない場合は、値が不明であることを示します。 |
UspsData
住所の USPS データ。uspsData
は、Address Validation API に送信されたすべての米国または PR の住所について、完全に入力される保証はありません。レスポンスの主要部分として uspsData を使用する場合は、バックアップ アドレスのフィールドをレスポンスに統合することをおすすめします。
JSON 表現 |
---|
{
"standardizedAddress": {
object ( |
フィールド | |
---|---|
standardizedAddress |
USPS 標準の住所。 |
deliveryPointCode |
2 桁の配達ポイント コード |
deliveryPointCheckDigit |
配達ポイントのチェック ディジット。この番号は、機械的にスキャンされたメールの場合、delivery_point_barcode の末尾に追加されます。Delivery_point_barcode、deliveryPointCheckDigit、郵便番号、ZIP+4 のすべての桁を加算すると、10 で割り切れる数値が得られます。 |
dpvConfirmation |
DPV の確認に使用できる値。1 文字を返すか、値を返しません。
|
dpvFootnote |
デリバリー ポイントの検証の脚注。1 つの文字列に複数の脚注をつなぎ合わせることができます。
|
dpvCmra |
住所が CMRA(Commercial Mail Received Agency)(顧客の郵便物を受け取る民間企業)かどうかを示します。1 文字を返します。
|
dpvVacant |
このお店は空席ですか?1 文字を返します。
|
dpvNoStat |
統計値のないアドレスですか、それとも有効なアドレスですか?No stat アドレスとは、継続的に占有されていない住所や、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)。 |