이 문서에서는 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는 주소를 수정해야 하는지 알려주는 여러 신호를 제공합니다.
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. 유효성 검사 세부사항
validationGranularity
이상의 ROUTE는 허용되지만 PREMISE 또는 SUBPREMISE
는 배송 가능성을 더 강력하게 나타냅니다.
2. 기타 신호
고객에게 주소 항목을 확인할지 결정할 때 결과는 조사할 구성요소를 결정하기 위해 다음도 제공합니다.
| 추론된 데이터 |
hasInferredComponents 필드가 true이면 API가 다른 주소 구성요소에서 수집한 정보를 채웠다는 것을 알 수 있습니다.
|
|---|---|
| 교체된 데이터 |
hasReplacedComponents 필드가 true이면
API가 입력된 데이터를 주소를 유효하게 만드는 것으로 간주되는 데이터로 대체했습니다.
|
3. 미국 주소 신호
미국 주소에만 적용되는 특정 필드는 로직에서 고객에게 세부정보를 확인해야 함을 나타냅니다. 다음 중 하나라도 해당합니다.
dpvConfirmation
|
S
|
|---|---|
| 주소 응답 | missingComponentTypes 값이 있는
subpremise 필드를 포함합니다.
|
주소 수락
결과에서 주소를 배송할 수 있으며 다운스트림 프로세스에서 추가 고객 상호작용 없이 사용할 수 있다고 높은 신뢰도를 제공하는 경우 주소를 수락합니다.
신호 수락
Address Validation API는 주소를 확인해야 하는지 알려주는 여러 신호를 제공합니다.
1. 유효성 검사 세부사항
PREMISE 이상의 validationGranularity는 허용되지만 경우에 따라 ROUTE는 여전히 배송 가능한 주소를 나타냅니다.
2. 기타 신호
고품질 주소의 결과는 다음도 제공해야 합니다.
- 교체된 데이터 없음. 이 경우
hasReplacedComponents: FALSE입니다. - 추론된 구성요소 없음. 이 경우
hasInferredComponents: FALSE입니다.
3. 미국 주소 신호
미국 주소에만 적용되는 특정 필드는 배송할 수 있는 고품질 주소를 나타냅니다. 허용되는 미국 주소의 경우 다음이 표시됩니다.
dpvConfirmation
|
Y
|
|---|