이 문서에서는 Address Validation API가 시스템에서 확인 동작을 보장하는 주소에 응답 신호를 제공하는 여러 실제 시나리오를 설명합니다. 컨텍스트는 유효성 검사 로직 빌드의 워크플로 개요를 참고하세요.
일반적인 예: 확인
다음 예는 거리 이름이 유사한 대도시 지역의 사례를 보여줍니다. 사용자가 미국 워싱턴주 커클랜드의 Google 빌딩 D 주소를 입력하려고 한다고 가정해 보겠습니다. 그러나 도시로 커클랜드가 아닌 시애틀로 실수로 들어갔습니다.
주소 입력됨 | 리전 |
---|---|
건물 D, 451 7th Avenue South, Seattle, WA 98033 | 미국 |
교체된 데이터에 대한 결과
아래 예에서는 응답에서 발생하는 중요한 신호를 강조합니다.
{
"inputGranularity": "SUB_PREMISE",
"validationGranularity": "PREMISE_PROXIMITY",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete": true,
"hasUnconfirmedComponents": true
"hasReplacedComponents": true
}
PREMISE_PROXIMITY
는 건물 수준 주소의 근사치를 나타내지만 입력 시 제공되는 단위인 SUB_PREMISE
만큼 세부적이지는 않습니다.
응답에는 확인되지 않은 구성요소와 교체된 구성요소도 모두 포함되므로 조합은 이를 확인 카테고리로 추가합니다.
주소 구성요소를 쿼리하면 다음과 같은 문제 영역을 알 수 있습니다.
{
"componentName": {
"text": "451",
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
"componentName": {
"text": "98104",
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"replaced": true
}
...
{
"componentName": {
"text": "Building D",
"language_code": "en"
},
"componentType": "subpremise",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......
"unconfirmedComponentTypes": [
"street_number",
"subpremise"
]
이 경우 Address Validation API는 시애틀에 제공된 주소와 근접한 주소를 찾았으며 더 높은 수준의 구성요소인 우편번호를 대체하여 시애틀 주소를 확인합니다. 이는 유효한 대체 주소일 수 있지만 구성요소가 확인되지 않은 경우 사용자가 커클랜드와 같은 다른 주소가 아닌 시애틀 주소를 입력하도록 하는 것이 좋습니다.
예외적인 케이스 예시: 확인
다음 예는 다음과 같은 예외적인 사례 유형을 보여줍니다.
- 확인된 사소한 추론. Address Validation API는 국가, 우편번호 또는 주를 추론하지만 나머지는 모두 제공 및 확인됩니다. 세부사항과 확인 수준을 조합하면 사소한 추론이 가능해지면서 반드시 확인 작업이 필요하지는 않습니다.
- 예상치 못한 주소 구성요소가 확인되지 않았습니다. 확인되지 않은 주소 구성요소는 주소의 위험 수준에 추가됩니다. 확인을 보장할 수 있습니다.
- 예상치 못한 주소 구성요소가 확인됨. 이 구성요소는 올바른 주소를 위해 반드시 필요한 것은 아니며 Address Validation API는 출력에서 이 구성요소를 삭제합니다. 형식 지정 문제는 일반적으로 확인이 보장되지 않습니다.
확인된 사소한 추론
보다 세분화된 수준의 확인된 데이터와 결합하면 입력에 다음 유형의 구성요소 중 하나만 누락된 경우에도 API가 올바른 추론을 수행할 수 있습니다.
- 도시
- 상태
- 우편번호
- 국가
예를 들어 고객이 매사추세츠 스프링필드에 있는 맥도날드 식당의 유효한 상세 주소를 제공했지만 도시는 입력하지 않고 4자리 확장자 없이 우편번호를 입력했다고 가정해 보겠습니다.
주소 입력됨 | 리전 |
---|---|
서울특별시 서대문구 창천동 111-111 | 미국 |
도시 누락에 대한 판결
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
Address Validation API가 배송 가능 주소를 생성하기 위해 상위 수준 구성요소를 추론하는 경우 시스템의 데이터가 정확하다고 확신할 수 있습니다. 넓은 지리적 지역을 나타내는 추론된 구성요소가 보다 세분화된 확인된 주소 구성요소와 더 쉽게 일치되기 때문입니다. 미국의 Springfield와 같이 도시 이름이 반복되는 국가에서도 도시 이름과 결합된 다른 구성요소가 고유한 주소를 제공할 수 있습니다.
위의 예에서 모든 주소 구성요소를 검사하면 모든 구성요소가 확인되어 Address Validation API에 저장된 데이터와 일치하며 서비스에서 두 개의 상위 수준 구성요소도 추론한다는 것을 알 수 있습니다.
{
"componentName": {
"text": "Springfield",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "1806"
},
"componentType": "postal_code_suffix",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
예기치 않은 주소 구성요소가 확인되지 않음
이 시나리오는 구성요소가 확인되지 않을 때 확인의 중요성을 보여줍니다. 주소 구성요소가 예기치 않은 경우 Address Validation API가 출력에서 주소 구성요소를 삭제합니다. 이러한 경우 위험 수준과 신뢰도에 따라 주소를 수락하거나 고객에게 재확인할 수 있습니다.
예를 들어 고객이 우편 당국에서 무시하는 무해한 정보를 입력하는 경우가 많은 지역의 주소일 수 있습니다. 이 경우 개발자는 주소를 수락합니다. 하지만 경우에 따라 확인되지 않은 구성요소가 고객이 원하는 것과 다를 수도 있습니다.
주소 입력됨 | 리전 |
---|---|
1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry | 프랑스 |
예기치 않은 주소 구성요소에 대한 결과가 확인되지 않음
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"unconfirmedComponents": true
}
Address Validation API는 확인되지 않은 구성요소가 포함된 결과 외에도 다음과 같은 형식의 주소를 반환합니다.
"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",
확인되지 않은 구성요소를 스캔하면 API가 반환된 주소에서 la caritat 2를 삭제했음을 알 수 있습니다.
{
"componentName": {
"text": "la caritat 2",
"languageCode": "fr"
},
"componentType": "sublocality_level_1",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
"unexpected": true
}
예기치 않은 주소 구성요소로 확인됨
이 예에서는 제공된 주소에 영국 카운티가 포함되는 것을 보여주며, 이는 일반적인 방식입니다. 하지만 이는 영국 우편 기관의 요구사항이 아니므로 기본적으로 무시됩니다. postoffice.co.uk와 영국 및 국제 우편물 처리 방법을 참조하세요.
따라서 고객이 영국 주소에 있는 카운티를 제공하는 경우 서비스는 이를 예상치 못한 입력으로 평가합니다.
주소 입력됨 | 리전 |
---|---|
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP | 영국 |
예기치 않은 주소 구성요소가 확인됨에 대한 결과
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE"
}
여기서 address_complete
는 false로 평가되며 주소 구성요소를 분석하면 예기치 않은 플래그가 나타납니다.
{
"componentName": {
"text": "Gloucestershire",
"languageCode": "en"
},
"componentType": "administrative_area_level_2",
"confirmationLevel": "CONFIRMED",
"unexpected": true
}
Gloucestershire는 입력한 주소의 올바른 카운티이지만 주소 자체의 형식이 잘못되었습니다. Address Validation API는 적절한 형식 지정을 위한 정보도 평가합니다.