주소 확인

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Address Validation API를 사용하여 주소 유효성을 검사하려면 validateAddress 메서드 (REST) 또는 ValidateAddress 메서드 (gRPC)를 호출합니다. 이 문서에서는 REST를 예로 사용하지만 이 접근 방식은 gRPC와 유사합니다.

주소를 확인한 후 선택적으로 provideValidationFeedback 메서드 (REST) 또는 ProvideValidationFeedback 메서드 (gRPC)를 호출하여 주소 유효성 검사 결과에 대한 정보를 Google에 반환할 수 있습니다. 자세한 내용과 예는 주소 확인 의견 제공을 참고하세요.

주소 확인 요청

validateAddress 메서드에 POST 요청을 전송하여 주소를 검증합니다.

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 필드(postalAddress 유형)에는 addressLines에 하나 이상의 항목이 포함되어야 합니다.

  • regionCode 필드는 선택사항입니다. 생략하면 API가 주소에서 지역을 추론합니다. 하지만 최상의 성능을 위해 regionCode를 알고 있다면 포함하는 것이 좋습니다. 지원되는 리전 목록은 지원되는 리전을 참조하세요.

  • address 필드의 총 길이는 280자(영문 기준)로 제한됩니다.

주소 확인 시 CASSTM 사용 설정(선택사항)

미국 우편 서비스® (USPS®)1코딩 정확도 지원 시스템 (CASSTM)을 유지하여 주소 확인 제공업체를 지원하고 인증합니다. Address Validation API와 같은 CASS CertifiedTM 서비스는 주소에서 누락된 정보를 입력하고, 표준화하고, 가장 정확한 최신 주소를 제공하도록 업데이트할 수 있는 기능으로 확인되었습니다.

'US' 및 'PR' 리전에 한해 요청 본문에서 enableUspsCasstrue로 설정하여 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 필드로, 주소의 지오코드 정보가 포함됩니다.

  • 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"
}

업데이트된 주소 확인하기

주소 하나에 대해 Address Validation API를 여러 번 호출해야 하는 경우도 있습니다. 예를 들어 사용자는 첫 번째 유효성 검사 결과를 확인한 후 주소를 변경하거나 수정할 수 있습니다. 그런 다음 업데이트된 주소에 대해 두 번째 검증을 수행합니다.

각 Address Validation API 호출은 응답의 responseId 필드에 고유한 값을 반환합니다. 유효성 검사하려는 주소의 유효성을 다시 검사해야 한다면 모든 후속 요청에 대해 previousResponseId 필드의 첫 번째 유효성 검사 응답의 responseId를 Address Validation API에 전달합니다.

새 요청에 previousResponseId 필드를 포함하면 API의 전반적인 정확성을 개선할 수 있습니다.

예를 들어 위에 나온 응답에는 responseId 필드가 포함되어 있습니다.

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

그런 다음 상세 주소를 1600에서 1500으로 변경하여 주소를 다시 확인합니다. 주소를 재검증할 때 첫 번째 응답의 responseId 값과 함께 previousResponseId 필드를 포함합니다.

{
  "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을 따릅니다.