- HTTP リクエスト
- リクエストの本文
- レスポンスの本文
- 住所
- ValidationResult
- 判断
- 粒度
- 住所
- AddressComponent
- ComponentName
- 確認レベル
- ジオコード
- 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 互換モードを有効にします。これは コンポーネント化された |
レスポンスの本文
成功すると、レスポンスの本文に次の構造のデータが含まれます。
住所確認リクエストへのレスポンス。
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 によって拒否されませんが、情報は破棄され、レスポンスで返されません。 |
ValidationResult
住所確認の結果。
JSON 表現 |
---|
{ "verdict": { object ( |
フィールド | |
---|---|
verdict |
全体的な判定フラグ |
address |
ジオコードではなく住所自体に関する情報。 |
geocode |
住所がジオコーディングされた場所と場所に関する情報です。 |
metadata |
成果物に関連するその他の情報。Address Validation API に送信されるすべてのアドレスに |
uspsData |
USPS が提供する追加の配送フラグ。リージョン |
判断
住所確認の結果とジオコードの概要。
JSON 表現 |
---|
{ "inputGranularity": enum ( |
フィールド | |
---|---|
inputGranularity |
入力アドレスの粒度。これは入力アドレスを解析した結果であり、検証シグナルは提供されません。検証シグナルについては、以下の たとえば、入力アドレスに特定のアパート番号が含まれている場合、 |
validationGranularity |
API が住所を完全に検証できる粒度レベル。たとえば、 住所コンポーネントごとの検証結果は |
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」などの入力)。未解決のトークンは有効な番地ではないので、 |
住所コンポーネント
番地、市区町村、都道府県などの住所コンポーネントを表します。
JSON 表現 |
---|
{ "componentName": { object ( |
フィールド | |
---|---|
componentName |
このコンポーネントの名前。 |
componentType |
住所コンポーネントのタイプ。可能性のあるタイプのリストについては、表 2: プレイス サービスで返されるその他のタイプをご覧ください。 |
confirmationLevel |
コンポーネントが正しいという確信のレベルを示します。 |
inferred |
構成要素が入力の一部ではなかったものの、住所の場所が推測され、完全な住所のものであると判断されたことを示します。 |
spellCorrected |
コンポーネント名のスペルが少し間違って修正されたことを示します。たとえば、間違った順序で表示される 2 文字を入力したなどです。外観が変更されていることを示します。 |
replaced |
コンポーネントの名前が完全に別の名前に置き換えられていることを示します。たとえば、間違った郵便番号が、住所に対して正しい郵便番号に置き換えられていることを示します。これは外観上の変更ではなく、入力コンポーネントが別のコンポーネントに変更されました。 |
unexpected |
指定された地域の住所に存在しない住所コンポーネントを示します。入力の一部であったため、保持しています。 |
コンポーネント名
コンポーネントの名前のラッパー。
JSON 表現 |
---|
{ "text": string, "languageCode": string } |
フィールド | |
---|---|
text |
名前のテキスト。たとえば、番地の場合は「5th Avenue」、番地の場合は「1253」です。 |
languageCode |
BCP-47 言語コード。コンポーネント名が言語(番地など)に関連付けられていない場合、この属性は存在しません。 |
確認レベル
確認レベルのさまざまな値。
列挙型 | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED |
デフォルト値。この値は使用されません。 |
CONFIRMED |
このコンポーネントが存在し、アドレスの残りの部分で意味を持つことを確認できました。 |
UNCONFIRMED_BUT_PLAUSIBLE |
このコンポーネントを確認できませんでしたが、このコンポーネントが存在する可能性はあります。たとえば、特定の番地が不明な通りに既知の有効な範囲内の電話番号です。 |
UNCONFIRMED_AND_SUSPICIOUS |
このコンポーネントは確認されておらず、不適切である可能性があります。たとえば、残りの住所に該当しない地区などが該当します。 |
ジオコード
入力がジオコーディングされた場所に関する情報が含まれます。
JSON 表現 |
---|
{ "location": { object ( |
フィールド | |
---|---|
location |
入力のジオコード位置情報。 場所 ID は、住所、緯度と経度の座標、Plus Code よりも優先的に使用します。運転ルートのルーティングや計算に使用する座標は常に、その座標に最も近い道路にスナップされます。目的地に速くまたは安全につながる道路ではなく、アクセス ポイントの近くにない場合もあります。また、位置情報がリバース ジオコーディングされている場合、返される住所が元の住所と一致するという保証はありません。 |
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)は 2 つの形式の位置情報参照です。14mx14m(1/8000 度)以下の長方形を定義するグローバル コード、および複合コードであり、接頭辞を参照場所に置き換えます。
JSON 表現 |
---|
{ "globalCode": string, "compoundCode": string } |
フィールド | |
---|---|
globalCode |
プレイスのグローバル(フル)コード(「9FWM33GV+HQ」など)。1/8000 x 1/8000 度(14 x 14 m 程度)を表す。 |
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 |
必須。ビューポートの要点。 |
住所のメタデータ
住所のメタデータ。Address Validation API に送信されるすべてのアドレスに metadata
が完全に入力されるとは限りません。
JSON 表現 |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
フィールド | |
---|---|
business |
ビジネスの住所を示します。設定されていない場合は、値が不明であることを示します。 |
poBox |
PO ボックスの住所を示します。設定されていない場合は、値が不明であることを示します。 |
residential |
居住地の住所を示します。設定されていない場合は、値が不明であることを示します。 |
usps データ
住所の USPS データ。uspsData
は、Address Validation API に送信されるすべての米国住所または PR アドレスについて、完全に情報が入力されているとは限りません。レスポンスのメイン部分として 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(商用メール受信代理店)であるかどうかを示します。CMRA はクライアント宛てのメールを受信するプライベート ビジネスです。1 文字を返します。
|
dpvVacant |
この場所は空席ですか?1 文字を返します。
|
dpvNoStat |
これはデータなしの住所ですか、それとも有効な住所ですか。米国の住所は、継続的に占有されていない住所または USPS が対応していない住所です。1 文字を返します。
|
carrierRoute |
運送業者の経路コード。1 文字のプレフィックスと 3 桁のルート指定子で構成される 4 文字のコード。 接頭辞:
|
carrierRouteIndicator |
運送業者の送料レートの表示 |
ewsNoMatch |
配送先住所は照合可能ですが、EWS ファイルには完全一致が利用可能になる予定です。 |
postOfficeCity |
主要な郵便局の都市。 |
postOfficeState |
メインの郵便局の都道府県。 |
abbreviatedCity |
都市名の略称。 |
fipsCountyCode |
FIPS 郡コード。 |
county |
国名。 |
elotNumber |
Enhanced Line of Travel(eLOT)番号。 |
elotFlag |
eLOT 昇順フラグ/降順フラグ(A/D)。 |
lacsLinkReturnCode |
LACSLink のリターンコード。 |
lacsLinkIndicator |
LACSLink インジケーター。 |
poBoxOnlyPostalCode |
私書箱のみの郵便番号。 |
suitelinkFootnote |
番地や高層の記録とスイートの情報が一致する脚注。ビジネス名の一致が見つかった場合は、2 番目の番号が返されます。
|
pmbDesignator |
PMB(Private Mail Box)ユニット指定子。 |
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 |
最初の住所の行。 |
firm |
会社名。 |
secondAddressLine |
2 つ目の住所行。 |
urbanization |
プエルトリコの都市名。 |
cityStateZipAddressLine |
市区町村 + 都道府県 + 郵便番号 |
city |
市町村名。 |
state |
2 文字の州コード。 |
zipCode |
郵便番号(例: 10009)。 |
zipCodeExtension |
4 桁の郵便番号の拡張番号(例: 5023)。 |