주소 확인 요청 보내기

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"

PostalAddress 유형인 요청 본문의 address 필드는 addressLines에 하나 이상의 항목을 포함해야 합니다.

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

  • address 필드의 전체 길이는 280자로 제한됩니다.

주소 확인 시 CASSTM를 선택적으로 사용 설정

미국 Postal Service® (USPS®)1에서 코딩 정확성 지원 시스템 (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 배열에서 전체 주소를 두 개의 문자열로 지정할 수도 있습니다.

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

주소 확인 응답

요청이 성공하면 서버가 HTTP 200 OK 상태 코드와 검증된 주소에 대한 정보를 포함하는 응답 본문으로 응답합니다.

응답의 result 필드에는 ValidationResult 객체가 포함됩니다. 이 객체에는 다음이 포함됩니다.

  • 주소에 대한 세부정보가 포함된 주소 유형의 address 필드.

  • 주소의 지오코드 정보가 포함된 지오코드 유형의 geocode 필드입니다.

  • 결과 유형의 verdict 필드로, 주소 유효성 검사 및 지오코드 결과가 포함됩니다.

  • 주소의 메타데이터를 포함하는 AddressMetadata 유형의 metadata 필드.

  • 주소에 대한 USPS 데이터를 포함하는 USPSData 유형의 uspsData 필드. 이 데이터는 미국과 푸에르토리코의 주소에만 사용할 수 있습니다.

다음 응답에 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 필드에 고유한 값을 반환합니다. 검증하려는 주소의 유효성을 다시 검사해야 하는 경우 Address Validation API에 대한 모든 후속 요청의 previousResponseId 필드에 첫 번째 유효성 검사 응답의 responseId를 전달합니다.

새 요청에 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 필드에 새 값을 반환합니다. 그러나 이후의 모든 주소 업데이트 호출에서 첫 번째 응답의 responseId 값을 previousResponseId 필드에 계속 전달합니다.

오류 처리

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은 United States Postal Service®의 비독점 라이선스 수혜자입니다. 다음 상표는 United States Postal Service®가 소유하며 United States Postal Service®, CASSTM, CASS CertifiedTM의 승인 하에 사용됩니다. ORDINAL