住所を確認する

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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"

リクエスト本文の address フィールドには PostAddress 型があり、addressLines に少なくとも 1 つのエントリが含まれている必要があります。

  • regionCode フィールドは省略可能です。省略した場合、API は住所から地域を推定します。ただし、最適なパフォーマンスを得るには、regionCode を含めることをおすすめします。サポートされているリージョンの一覧については、サポートされているリージョンをご覧ください。

  • address フィールドの合計長は 280 文字に制限されています。

オプションで、住所の確認時に CASSTM を有効にする

United States Post Service®（USPS®）1は、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
}

住所確認レスポンス

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

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

  • 住所の詳細情報を含む、Address 型の address フィールド。

  • 住所のジオコード情報を含む Geocode 型の geocode フィールド。

  • 住所検証とジオコード結果を含む Verdict 型の verdict フィールド。

  • AddressMetadata 型の metadata フィールド。住所のメタデータが含まれます。

  • 住所の USPS データを含む USPSData 型の uspsData フィールド。このデータは、米国とプエルトリコの住所でのみ利用可能です。

次のレスポンスでは、addressComplete が true に設定されており、このアドレスが完全に有効であることがレスポンスに示されています。したがって、これ以上の検証は必要ありません。レスポンスで住所の一部が無効であることが示されている場合は、ユーザーに住所入力の確認を求めるメッセージが表示されます。

{
  "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 フィールドに一意の値を返します。検証しようとしているアドレスを再検証する必要がある場合は、すべてのフォローアップ リクエストの previousResponseId フィールドにある最初の検証レスポンスの responseId を Address Validation API に渡します。

新しいリクエストに previousResponseId フィールドを追加すると、API の全体的な精度を向上させることができます。

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

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

次に、番地を 1600 から 1500 に変更して、住所を再検証します。住所を再検証するときは、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"
  }
}

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

  1. Google Maps Platform は、米国の郵便サービス® の非独占的なライセンシーです。次の商標は、米国郵便サービス®が所有し、許可を得て使用しています。米国郵便サービス®、CASSTM、CASS 認定 TM です。⏎