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' 리전에 한해 요청 본문에서 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필드로, 주소의 지오코드 정보가 포함됩니다.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"
}
}
오류 및 오류 처리에 대한 자세한 내용은 오류를 참조하세요.
-
Google Maps Platform은 미국 우편 서비스®의 비배타적 라이선스 수혜자입니다. 이 상표는 미국 우편 서비스® 소유이며 미국 우정 서비스 , CASSTM, CASS 인증TM을 따릅니다. 六