이 문서에서는 Address Validation API의 다양한 응답을 처리하기 위해 주소 확인 시스템을 빌드하는 프로세스를 설명합니다. 응답을 올바르게 사용하기 위한 로직을 빌드하는 방법, API의 다른 신호를 조사하는 방법, 고객에게 추가 정보를 요청하는 메시지를 언제 어떻게 표시해야 하는지 설명합니다.
일반적으로 API 응답은 시스템에서 주소를 다음과 같이 처리할 방법을 결정합니다.
- 해결: 주소 품질이 낮습니다. 추가 정보를 요청하는 메시지가 표시됩니다.
- 확인: 주소가 고품질이지만 입력 주소와는 다른 내용이 있습니다. 확인 메시지가 표시될 수 있습니다.
- 수락: 고품질의 주소입니다. 제공된 주소를 수락할 수 있습니다.
키 용도
이 문서는 API 응답을 가장 잘 분석하고 제공된 주소로 수행할 다음 작업을 결정하도록 시스템을 수정하는 데 도움이 됩니다. 다음 의사 코드는 가능한 흐름을 보여줍니다.
if (the API response indicates significant problems in the address)
FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
CONFIRM - confirm with the user that the address is correct
else
ACCEPT - continue with the address returned by the API.
정확한 로직은 상황에 따라 다릅니다. 자세한 내용은 구현 가이드를 참고하세요. 확장 구성요소 라이브러리에 있는 이 로직의 오픈소스 구현을 사용할 수도 있습니다.
워크플로 개요
아래 표에는 시스템에서 수행할 두 가지 작업이 요약되어 있습니다.
- 수정, 확인, 수락 동작을 기반으로 사용할 워크플로
- 응답에서 확인해야 할 첫 번째 신호입니다. 여기에서 설명하는 신호는
verdict속성에서 가져오며 확인해야 할 유일한 신호는 아니지만 주소 품질을 나타내는 초기 지표를 제공합니다. 각 동작 유형은 조사가 필요할 수도 있는 추가 신호를 설명하는 이 문서의 섹션에 해당합니다.
| 시스템 동작 | |||
|---|---|---|---|
| 주소 수정 |
|
||
| 주소 확인 |
|
||
| 주소 수락 |
Address Validation API 응답은 매우 우수한 주소를 나타냅니다.
|
||
구현 안내
시스템이 Address Validation API의 신호에 응답하는 방식을 설계할 때 다음 권장사항을 따르면 보다 효과적인 응답 모델을 빌드할 수 있습니다. 하지만 이는 권장사항일 뿐이므로 구현은 비즈니스 모델에 적합해야 합니다.
| 유용한 정보 | 세부정보 | |
|---|---|---|
| 위험 수준 |
수정을 요청하는 메시지와 입력된 주소를 그대로 수락하는 것 사이에서 균형을 잡을 때는 상황에 대한 허용 범위를 고려하세요. |
Address Validation API는 다양한 신호를 반환하며, 위험 수준과 통합하여 검증 프로세스를 최적화할 수 있습니다. 예를 들어 주소에 확인되지 않은 번지가 있는 경우에도 주소를 수락할 수 있습니다. 반면 비즈니스 운영에서 높은 수준의 주소 정밀도가 필요한 경우 사용자에게 메시지를 표시할 수 있습니다. 두 카테고리 중 하나에 해당할 수 있는 예는 주소 허용 - 예시에서 미국 이외 지역의 번지수를 참고하세요. |
| 주소 허용 |
고객이 메시지에 응답하지 않는 경우 시스템에서 원래 항목을 수락하도록 하는 것이 좋습니다. |
이러한 경우 고객이 신축 공사와 같이 시스템에 없는 주소를 입력했을 수 있습니다. |
| 의견 보내기 |
주소 유효성 검사 요청을 다시 실행할 때 |
최종 답변을 어떻게 처리했는지 Google에 알릴 수 있습니다. 업데이트된 주소 처리를 참고하세요. |
주소 수정
결과에 배달할 수 없는 주소라고 명확하게 표시되면 주소를 수정하세요. 그러면 시스템에서 고객에게 필요한 정보를 제공하라는 메시지를 표시할 수 있으며, 이후 워크플로를 다시 실행하여 배송 가능한 주소를 얻을 수 있습니다.
신호 수정
Address Validation API는 여러 신호를 제공하여 주소를 수정해야 하는지 여부를 알려줍니다.
1. 검증 세부사항 및 누락된 구성요소
다음 두 신호를 통해 문제가 있는 주소를 가장 잘 알 수 있습니다.
validationGranularity필드가OTHER일 때마다 시스템은 주소 구성요소 신호를 조사하여 오류가 발생한 위치와 해결 방법을 자세히 알아봐야 합니다.- 후처리된
address객체가missingComponentTypes필드를 반환할 때마다 시스템은 해당 구성요소를 확인해야 합니다. 구성요소가 누락된 경우에도 주소가 불완전하여 배송할 수 없게 됩니다.
2. 기타 신호
Address Validation API는 특정 문제를 진단하는 데 도움이 되는 다른 신호도 제공합니다.
| 의심스러운 구성요소 | 구성요소의 확인 수준 enum이 UNCOMFIRMED_AND_SUSPICIOUS인 경우 구성요소가 잘못되었을 수 있습니다.
|
|---|---|
| 해결되지 않은 구성요소 | unresolvedToken은 주소의 유효한 부분으로 인식되지 않는 입력의 일부입니다. |
3. 미국 주소 신호
미국 주소에만 적용할 수 있는 특정 필드는 해당 주소를 배송할 수 없으며 수정해야 한다는 유용한 신호를 제공합니다. 수정이 필요한 주소의 경우 다음과 같이 표시됩니다.
dpvConfirmation
|
N, D 또는 비어 있습니다.
|
|---|
dpvConfirmation에 관한 자세한 내용은 미국 주소 처리를 참고하세요.
주소 확인
확인 결과에서 Address Validation API가 검증된 주소를 생성하기 위해 주소 구성요소를 추론하거나 변경했다고 표시되면 주소를 확인합니다. 이 경우 배송 가능한 주소가 있지만 실제 주소가 고객이 의도한 주소임을 더 확신하는 것이 좋습니다.
고객에게 올바른 프롬프트를 제공하기 위해 로직은 서비스에서 플래그한 구성요소를 식별하여 어떤 작업 또는 구성요소에 적용된 API에 플래그를 지정합니다(예: inferred, replaced, spellCorrected).
참조에서 AddressComponent를 확인하세요.
신호 확인
Address Validation API는 주소 확인 여부를 알려주는 여러 신호를 제공합니다.
1. 검증 세부사항
ROUTE 이상의 validationGranularity이 허용되지만 PREMISE 또는 SUBPREMISE는 더 강력한 전달 가능성을 제공합니다.
2. 기타 신호
고객과 함께 주소 입력을 확인하기로 결정할 때 조사 결과는 어떤 구성요소를 조사할지 결정하기 위해 다음도 제공합니다.
| 추론된 데이터 | hasInferredComponents 필드가 true이면 API가 다른 주소 구성요소에서 얻은 정보를 채운 것입니다.
|
|---|---|
| 대체된 데이터 | hasReplacedComponents 필드가 true이면 API가 입력된 데이터를 주소를 유효하다고 간주한 데이터로 교체했습니다.
|
3. 미국 주소 신호
미국 주소에만 적용되는 특정 필드는 로직에서 고객에게 세부정보를 확인해야 함을 나타냅니다. 다음 중 하나가 적용됩니다.
dpvConfirmation
|
S
|
|---|---|
| 주소 응답 | 값이 subpremise인 missingComponentType 필드를 포함합니다.
|
주소 수락
확인 결과에서 해당 주소를 전달할 수 있고 다운스트림 프로세스에서 추가 고객 상호작용 없이 사용할 수 있다는 확신이 있을 때 주소를 수락합니다.
신호 수락
Address Validation API는 주소 확인 여부를 알려주는 여러 신호를 제공합니다.
1. 검증 세부사항
validationGranularity PREMISE 이상이 허용되지만 경우에 따라 ROUTE는 여전히 배송 주소를 나타냅니다.
2. 기타 신호
고품질 주소에 대한 결과에는 다음 정보도 표시되어야 합니다.
- 교체된 데이터 없음. 이 경우는
hasReplacedComponents: FALSE입니다. - 유추된 구성요소 없음. 이 경우는
hasInferredComponents: FALSE입니다.
3. 미국 주소 신호
미국 주소에만 적용되는 특정 필드는 배송이 가능한 고품질 주소를 나타냅니다. 허용되는 미국 주소의 경우 다음과 같이 표시되어야 합니다.
dpvConfirmation
|
Y
|
|---|