このページは Cloud Translation API によって翻訳されました。

住所確認リクエストを送信する

Address Validation API を使用して住所を検証するには、validateAddress メソッド（REST）または ValidateAddress メソッド（gRPC）を呼び出します。このドキュメントでは例として REST を使用していますが、このアプローチは gRPC と似ています。

住所を検証した後、必要に応じて provideValidationFeedback メソッド（REST）または ProvideValidationFeedback メソッド（gRPC）を Google に返すことができます。情報と例については、住所確認のフィードバックを提供するをご覧ください。

住所確認リクエスト

住所を検証するには、POST リクエストを validateAddress メソッドに送信します。

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

検証する住所を定義する JSON 本文をリクエストに渡します。

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

PostalAddress 型のリクエスト本文の address フィールドには、addressLines のエントリが 1 つ以上含まれている必要があります。

regionCode フィールドは省略可能です。省略すると、API は住所からリージョンを推測します。ただし、最高のパフォーマンスを得るには、regionCode を含めることをおすすめします。サポートされているリージョンの一覧については、サポートされているリージョンをご覧ください。
address フィールドの合計長は 280 文字に制限されています。

必要に応じて、住所の検証時に CASSTM を有効にする

米国郵政公社（USPS®）¹は、住所検証プロバイダのサポートと認定のために、Coding Accuracy Support System（CASSTM）を維持しています。Address Validation API などの CASS CertifiedTM サービスは、住所にない情報を記入して標準化し、最新の正確な住所が表示されるように更新できる機能が確認されています。

「US」リージョンと「PR」リージョンの場合のみ、リクエスト本文で enableUspsCass を true に設定することで、必要に応じて CASS 処理を有効にできます。

CASS を使用する場合は、市区町村、都道府県、郵便番号に加えて、番地を含む住所を指定することをおすすめします。

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

また、addressLines 配列の 2 つの文字列として完全な住所を指定することもできます。

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Address Validation のレスポンス

リクエストが成功すると、サーバーは HTTP 200 OK ステータスコードと、検証されたアドレスに関する情報を含むレスポンス本文で応答します。

レスポンスの result フィールドに ValidationResult オブジェクトが含まれます。このオブジェクトには次のものが含まれます。

Address タイプの address フィールド。住所に関する詳細情報が含まれます。
住所のジオコード情報を含む、Geocode タイプの geocode フィールド。

注: address と geocode の違いについては、住所とジオコードをご覧ください。
住所の検証とジオコーディングの結果を含む、Verdict 型の verdict フィールド。
住所のメタデータを含む AddressMetadata 型の metadata フィールド。
USPSData 型の uspsData フィールド。住所の USPS データが含まれます。このデータは、米国とプエルトリコの住所でのみ使用できます。

次のレスポンスには true に設定された addressComplete が含まれているため、レスポンスはこの住所が完全に有効であることを示すため、それ以上の検証は必要ありません。レスポンスで住所の一部が無効であることが示された場合は、住所の入力を確認するようにユーザーに促します。

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

更新された住所を検証する

場合によっては、1 つの住所に対して Address Validation API を複数回呼び出す必要があります。たとえば、ユーザーが最初の検証結果を確認した後に、住所を変更または修正したとします。次に、更新された住所に対して 2 回目の検証を行います。

Address Validation API の呼び出しごとに、レスポンスの responseId フィールドで一意の値を返します。検証する住所を再検証する必要がある場合は、Address Validation API へのすべてのフォローアップリクエストで、previousResponseId フィールドの最初の検証レスポンスの responseId を渡します。

新しいリクエストに previousResponseId フィールドを含めると、API の全体的な精度の向上に役立ちます。

たとえば、上のレスポンスには responseId フィールドが含まれています。

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

次に、番地を 1,600 から 1,500 に変更して住所を再検証します。住所を再検証するときは、previousResponseId フィールドに最初のレスポンスの responseId の値を含めます。

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

CASS を使用したリクエストの場合:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

その後の呼び出しごとに、responseId フィールドに新しい値を返します。ただし、住所の更新に対する後続の呼び出しでは、引き続き previousResponseId フィールドの最初のレスポンスの responseId の値を渡します。

エラー処理

Address Validation API は、メソッド呼び出しへのレスポンスの一部としてエラーメッセージを返します。たとえば、リクエストで API キーを省略すると、メソッドは以下を返します。

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

必須の本文パラメータ（addressLines など）を省略すると、メソッドは以下を返します。

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

エラーとエラー処理の詳細については、エラーをご覧ください。

Google Maps Platform は、米国郵政公社の非独占的なライセンシーです。米国郵政公社の商標は米国郵政公社が所有し、許可を得て使用しています。United States Postal Service®、CASSTM、CASS CertifiedTM Ұ。