Google Address Validation API V2(Java)を使用して、
住所を検証する方法についてご紹介します。
住所を検証後、検証した結果のフィードバックを送ります。
APIを利用する環境の準備から始める場合や、コードを実行する際は、
⧉[Google Address Validation API(V1)] Javaで住所を検証する
を参照ください。
| No | 目次 | |
|---|---|---|
| 1 | 住所を検証 | |
| 1 | スコープ | |
| 2 | 実行 | |
| 3 | レスポンスの内容 | |
| 2 | 検証結果をフィードバック | |
| 1 | スコープ | |
| 2 | 実行 | |
| 3 | レスポンスの内容 |
1. 住所を検証
指定した住所を検証します。
1.1. スコープ
このAPIを実行するには、以下のスコープを指定してください。
https://www.googleapis.com/auth/cloud-platform
1.2. 実行
public static void main(String[] args) throws Exception{
try(AddressValidationClient client = AddressValidationClient.create()){
PostalAddress.Builder address = PostalAddress.newBuilder();
address.addAllAddressLines(Arrays.asList("678 Lafayette Ave Suite 2B"));
ValidateAddressRequest.Builder builder = ValidateAddressRequest.newBuilder();
builder.setAddress(address.build());
ValidateAddressResponse res = client.validateAddress(builder.build());
System.out.println(res);
}
}
1.2.1. HTTPリクエスト
POST: https://addressvalidation.googleapis.com/v1:validateAddress
が実行されます。
1.2.2. クエリパラメータ
クエリパラメータはありません。
1.2.3. リクエストボディ
ValidateAddressRequest.Builderのsetメソッドにより、リクエストボディを追加できます。
build()メソッドでValidateAddressRequestインスタンスを取得し、
setAddress()に渡します。
| メソッド | 引数 | 説明 |
|---|---|---|
| setAddress | PostalAddress | 【必須】検証される住所 |
| setPreviousResponseId | String | 再検証をする必要がある場合のresponseId |
| setEnableUspsCass | Boolean | USPS CASS 互換モードを有効にするか |
| setLanguageOptions | LanguageOptions | 言語オプション |
| setSessionToken | String | オートコンプリート セッションを課金目的で識別する文字列 |
PostalAddress
| メソッド | 引数 | 説明 |
|---|---|---|
| setAddressLines | List<String> | 【必須】構造化されていない住所の下位部分を記述する行 |
| setRevision | Integer | PostalAddressのスキーマリビジョン |
| setRegionCode | String | 住所の国/地域に対応する CLDR 地域コード |
| setLanguageCode | String | 【将来拡張用(未使用)】入力住所の言語コード |
| setPostalCode | String | 住所の郵便番号 |
| setSortingCode | String | 国固有の付加的な並べ替えコード |
| setAdministrativeArea | String | その国/地域の郵便住所に使用される最上位の行政区域 |
| setLocality | String | 住所の市区町村の部分 |
| setSublocality | String | 住所の市区町村部分より下位の区分 |
LanguageOptions
| メソッド | 引数 | 説明 |
|---|---|---|
| setReturnEnglishLatinAddress | Boolean | google.maps.addressvalidation.v1.Addressを返すか |
1.3. レスポンスの内容
ValidateAddressResponse
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getResult | ValidationResult | 住所検証の結果 |
| getResponseId | String | レスポンスを識別するUUID |
ValidationResult
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getVerdict | Verdict | 全体の判定フラグ |
| getAddress | Address | ジオコードではなく、住所自体に関する情報 |
| getGeocode | Geocode | 住所がジオコーディングされた場所と場所に関する情報 |
| getMetadata | AddressMetadata | 配送可能性に関するその他の情報 |
| getUspsData | UspsData | USPSが提供する追加の配送フラグ |
| getEnglishLatinAddress | Address | プレビュー版（pre-GA）の機能 |
Verdict
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getInputGranularity | Granularity(enum) | 入力アドレスの粒度 |
| getValidationGranularity | Granularity(enum) | APIが住所を完全に検証できる粒度レベル |
| getGeocodeGranularity | Granularity(enum) | geocodeの粒度に関する情報 |
| getAddressComplete | Boolean | 未解決のトークンや想定外の住所要素 |
| getHasUnconfirmedComponents | Boolean | 分類または検証ができない住所コンポーネントが1つ以上あるか |
| getHasInferredComponents | Boolean | 入力に含まれていない住所コンポーネントが推定(追加)されたか |
| getHasReplacedComponents | Boolean | 少なくとも1つの住所コンポーネントが置き換えられたか |
Address
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getFormattedAddress | String | 後処理された住所 |
| getPostalAddress | PostalAddress | 郵送先住所として表される後処理された住所 |
| getAddressComponents | List<AddressComponent> | フォーマットおよび修正された住所の個々の住所コンポーネントと検証情報 |
| getMissingComponentTypes | List<String> | 正しい形式の送付先住所に含まれているはずだったコンポーネントのタイプが入力に含まれておらず推測できなかったもの |
| getUnconfirmedComponentTypes | List<String> | addressComponentsに存在するものの、正しいことを確認できなかったコンポーネントのタイプ |
| getUnresolvedTokens | List<String> | 解決できなかった入力内のトークン |
PostalAddress
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getRevision | Integer | PostalAddressのスキーマリビジョン |
| getRegionCode | String | 住所の国/地域に対応するCLDR地域コード |
| getLanguageCode | String | 【将来拡張用】入力住所の言語コード |
| getPostalCode | String | 住所の郵便番号 |
| getSortingCode | String | 国固有の付加的な並べ替えコード |
| getAdministrativeArea | String | その国/地域の郵便住所に使用される最上位の行政区域 |
| getLocality | String | 通常は住所の市区町村の部分 |
| getSublocality | String | 住所の市区町村部分より下位の区分 |
| getAddressLines | List<String> | 構造化されていない住所の下位部分を記述する行 |
AddressComponent
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getComponentName | ComponentName | コンポーネントの名前 |
| getComponentType | String | 住所コンポーネントのタイプ |
| getConfirmationLevel | ConfirmationLevel(enum) | コンポーネントが正しいことに関する確実性のレベル |
| getInferred | Boolean | 住所の場所として推定され完全な住所に対して提供されるべきだと判断されたか |
| getSpellCorrected | Boolean | コンポーネント名のスペルミスが修正されたか |
| getReplaced | Boolean | コンポーネントの名前がまったく別の名前に置き換えられたか |
| getUnexpected | Boolean | 指定された地域の郵便の宛先には含まれないはずの住所コンポーネントか |
ComponentName
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getText | String | 名前のテキスト |
| getLanguageCode | String | BCP-47言語コード |
Geocode
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getLocation | LatLng | 入力のジオコーディングされた場所 |
| getPlusCode | PlusCode | locationに対応するpluscode |
| getBounds | Viewport | ジオコーディングされた場所の境界 |
| getFeatureSizeMeters | Double | ジオコーディングされた場所のサイズ(メートル) |
| getPlaceId | String | この入力によってジオコーディングされる場所のPlaceID |
| getPlaceTypes | List<String> | 入力がジオコーディングされた場所のタイプ |
PlusCode
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getGlobalCode | String | 場所のグローバルコード |
| getCompoundCode | String | 場所の複合コード |
Viewport
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getLow | LatLng | ビューポートの下限 |
| getHigh | LatLng | ビューポートの最高点 |
LatLng
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getLatitude | Double | 緯度(-90.0〜90.0) |
| getLongitude | Double | 経度(-180.0〜180.0) |
AddressMetadata
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getBusiness | Boolean | ビジネスの住所であるか |
| getPoBox | Boolean | 私書箱の住所か |
| getResidential | Boolean | 居住地の住所であるか |
UspsData
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getStandardizedAddress | UspsAddress | USPS標準住所 |
| getDeliveryPointCode | String | 2桁の配送先コード |
| getDeliveryPointCheckDigit | String | 配送先のチェックディジット |
| getDpvConfirmation | String | DPV確認に使用できる値 |
| getDpvFootnote | String | 配送ポイントの検証の脚注 |
| getDpvCmra | String | 住所がCMRA（商業郵便受取所）か "Y"(アドレスはCMRA)、"N"(アドレスはCMRAではない) |
| getDpvVacant | String | 空いている場所か "Y"(住所が空)、"N"(この住所に空きがない) |
| getDpvNoStat | String | これは統計データのない住所か "Y"(このアドレスは有効ではない)、"N"(アドレスはアクティブ) |
| getDpvNoStatReasonCode | Integer | NoStatのタイプ |
| getDpvDrop | String | サイトの単一の受信可能にメールが配信されるか "Y"(メールはサイトの単一の受信担当者に配信)、"N"(メールはサイトの単一の受信担当者に配信されない) |
| getDpvThrowback | String | 郵便物が番地に配送されないか "Y"(住所に郵便物が配送されていない)、"N"(郵便物は番地に配信) |
| getDpvNonDeliveryDays | String | メールの配信が毎日行われていないか "Y"(メール配信は毎日行われるわけではない)、"N"(メール配信は毎日行われないことを示すものではない) |
| getDpvNonDeliveryDaysValues | Integer | 配達不能の日数を識別する整数 |
| getDpvNoSecureLocation | String | セキュリティ上の懸念により荷物が置かれないか "Y"(セキュリティ上の懸念により荷物は発送されない)、"N"(セキュリティ上の懸念により荷物が置かれないことを示すものではない |
| getDpvPbsa | String | アドレスがPBSAレコードと一致したか "Y"(アドレスがPBSAレコードと一致)、"N"(アドレスがPBSAレコードと一致しない) |
| getDpvDoorNotAccessible | String | フラグは、USPSがドアをノックして郵便物を配送できない住所か "Y"(ドアにアクセスできない)、"N"(ドアにアクセスできないことを示す) |
| getDpvEnhancedDeliveryCode | String | DPV戻りコード |
| getCarrierRoute | String | 運送業者のルートコード |
| getCarrierRouteIndicator | String | 運送業者のルートの送料の並べ替えインジケーター |
| getEwsNoMatch | Boolean | 配送先住所は照合可能だが、EWSファイルには完全一致がまもなく利用可能になるか |
| getPostOfficeCity | String | 主な郵便局の市区町村 |
| getPostOfficeState | String | メインの郵便局の州 |
| getAbbreviatedCity | String | 略称の都市 |
| getFipsCountyCode | String | FIPS郡コード |
| getCounty | String | 郡名 |
| getElotNumber | String | 拡張旅程（eLOT）番号 |
| getElotFlag | String | eLOT昇順/降順フラグ（A/D） |
| getLacsLinkReturnCode | String | LACSLink戻りコード |
| getLacsLinkIndicator | String | LACSLinkインジケーター |
| getPoBoxOnlyPostalCode | Boolean | 私書箱のみの郵便番号 |
| getSuitelinkFootnote | String | 道路や高層ビルのレコードから部屋の情報にマッチした脚注 "A"(SuiteLinkのレコードマッチング、ビジネス拠点の住所が改善された)、"00"(一致なし、ビジネスの住所は改善されない) |
| getPmbDesignator | String | PMB（私用メールボックス）の単位指定子 |
| getPmbNumber | String | PMB（私書箱）番号 |
| getAddressRecordType | String | 入力住所に一致する住所レコードのタイプ |
| getDefaultAddress | Boolean | デフォルトの住所が見つかったものの、より具体的な住所が存在するか |
| getErrorMessage | String | USPSデータの取得に関するエラーメッセージ |
| getCassProcessed | Boolean | リクエストがCASS処理されたか |
UspsAddress
| メソッド | 戻り値 | 説明 |
|---|---|---|
| getFirstAddressLine | String | 住所1行目 |
| getFirm | String | 企業名 |
| getSecondAddressLine | String | 住所の2行目 |
| getUrbanization | String | プエルトリコの都市化の名前 |
| getCityStateZipAddressLine | String | 市区町村+都道府県+郵便番号 |
| getCity | String | 市町村名 |
| getState | String | 2文字の州コード |
| getZipCode | String | 郵便番号 |
| getZipCodeExtension | String | 4桁の郵便番号の拡張コード |
Granularity
| 定義値 | 内容 |
|---|---|
| GRANULARITY_UNSPECIFIED | デフォルト値 |
| SUB_PREMISE | アパートなど、建物より下のレベルの検索結果 |
| PREMISE | 建物レベルの検索結果 |
| PREMISE_PROXIMITY | 住所の建物レベルの位置を推定するジオコード |
| BLOCK | 住所またはジオコードがブロック |
| ROUTE | ジオコードまたは住所が、道路、道路、高速道路など、経路を細かく制御している |
| OTHER | その他のすべての粒度は、提供できないためまとめてバケットにまとめられる |
ConfirmationLevel
| 定義値 | 内容 |
|---|---|
| CONFIRMATION_LEVEL_UNSPECIFIED | デフォルト値 |
| CONFIRMED | Googleは、この要素が存在し、住所の残りの部分のコンテキストで意味をなすことを確認 |
| UNCONFIRMED_BUT_PLAUSIBLE | 存在している可能性がある |
| UNCONFIRMED_AND_SUSPICIOUS | 間違っている可能性がある |
DPV確認に使用できる値
| 定義値 | 内容 |
|---|---|
| N | プライマリとセカンダリの番号の情報がDPVの確認に失敗 |
| D | 住所はメインの電話番号でのみDPV確認されており、予備の電話番号の情報がない |
| S | 住所はメインの電話番号でのみDPVが確認されており、予備の電話番号の情報はあったが確認されない |
| Y | メインの電話番号と予備の電話番号のDPVが確認された |
| アドレスはDPV確認用に送信されない |
NoStatのタイプ
| 定義値 | 内容 |
|---|---|
| 1 | IDA（InternalDropAddress） USPSから直接郵便物を受け取らないものの、それらにサービスを提供する送付先住所に配送されるアドレス |
| 2 | CDS まだ配達が完了していない住所。たとえば、区画やメインの番号は決まっているものの、利用人数の構造がまだ存在しない新しい区分など |
| 3 | 競合 実際にDPVで確認されていない住所 |
| 4 | CMZ（College、Military、OtherTypes） ZIP+4レコード。USPSによりデータが取り込まれている |
| 5 | 標準 住所が配信されていないことを表します。配信候補としてカウントされない |
| 6 | 二次必須 このアドレスには二次情報が必要 |
配送ポイントの検証の脚注
| 定義値 | 内容 |
|---|---|
| AA | ZIP+4ファイルと一致する入力アドレス |
| A1 | 入力アドレスがZIP+4ファイルと一致しない |
| BB | DPVに一致（すべてのコンポーネント） |
| CC | 第2の番号が一致せず、必須ではない |
| C1 | 第2の番号が一致しないが必須 |
| N1 | 高層住所に予備の番号がない |
| M1 | メインの電話番号がない |
| M3 | メインの番号が無効 |
| P1 | 入力された住所のPO、RR、HCの箱番号が入力されていない |
| P3 | 入力された住所のPO、RR、HCの箱番号が無効 |
| F1 | 軍施設の住所と一致する入力住所 |
| G1 | 入力住所が一般的な配送先住所と一致 |
| U1 | 一意の郵便番号に一致する入力住所 |
| PB | PBSAレコードと一致する入力アドレス |
| RR | PMB情報を含むDPV確認済み住所 |
| R1 | PMB情報のないDPV確認済み住所 |
| R7 | CarrierRouteR777またはR779のレコード |
| IA | 通知先住所を特定 |
| TA | 末尾のアルファをドロップして照合されるメインの数値 |
DPV戻りコード
| 定義値 | 内容 |
|---|---|
| Y | メインの電話番号と予備の電話番号のDPVが確認された |
| N | プライマリとセカンダリの番号の情報がDPVの確認に失敗 |
| S | 住所はメインの番号でのみDPVが確認され、セカンダリ番号の情報は確認されない |
| D | 住所はメインの電話番号でのみDPV確認されており、予備の電話番号の情報がない |
| R | 住所が確認されたが、ファントムルートR777とR779に割り当てられており、USPS配送は提供されていない |
運送業者のルートコード
| 定義値 | 内容 |
|---|---|
| C | キャリアルート（または都市ルート） |
| R | 地方道路 |
| H | 高速道路の契約ルート |
| B | 私書箱コーナー |
| G | 一般的な配信単位 |
住所レコードのタイプ
| 定義値 | 内容 |
|---|---|
| F | 会社 |
| G | 一般的な配信 |
| H | 建物/アパート |
| P | オフィスボックスのポスト |
| R | RURALROUTEまたはHIGHWAYCONTRACT |
| S | STREETRECORD |
2. 検証結果をフィードバック
住所を検証した結果のフィードバックを送信します。
2.1. スコープ
このAPIを実行するには、以下のスコープを指定してください。
https://www.googleapis.com/auth/cloud-platform
2.2. 実行
レスポンスを識別するUUIDは、ValidateAddressResponseのgetResponseId()
で取得できる値を設定します。
public static void main(String[] args) throws Exception{
try(AddressValidationClient client = AddressValidationClient.create()){
ProvideValidationFeedbackRequest.Builder builder = ProvideValidationFeedbackRequest.newBuilder();
builder.setResponseId("レスポンスを識別するUUID");
builder.setConclusion(ValidationConclusion.USER_VERSION_USED);
ProvideValidationFeedbackResponse res = client.provideValidationFeedback(builder.build());
System.out.println(res);
}
}
2.2.1. HTTPリクエスト
POST: https://addressvalidation.googleapis.com/v1:provideValidationFeedback
が実行されます。
2.2.2. クエリパラメータ
クエリパラメータはありません。
2.2.3. リクエストボディ
ProvideValidationFeedbackRequest.Builderのsetメソッドにより、リクエストボディを追加できます。
build()メソッドでProvideValidationFeedbackRequestインスタンスを取得し、
provideValidationFeedback()に渡します。
| メソッド | 引数 | 説明 |
|---|---|---|
| setResponseId | String | 【必須】レスポンスを識別するUUID |
| setConclusion | ValidationConclusion(enum) | 【必須】検証試行の結果 |
ValidationConclusion
| 定義値 | 内容 |
|---|---|
| VALIDATION_CONCLUSION_UNSPECIFIED | 未使用 |
| VALIDATED_VERSION_USED | AddressValidationAPIから返された住所のバージョンがトランザクションに使用されていた |
| USER_VERSION_USED | お客様から提供された住所のバージョンが取引に使用された |
| UNVALIDATED_VERSION_USED | 前回の検証後に入力されたが、再検証されていないバージョンの住所がトランザクションに使用されていた |
| UNUSED | 取引は放棄され、住所は使用されなかった |
2.3. レスポンスの内容
レスポンスはありません。
失敗すると例外が返ります。
おしまい。。