이 문서에서는 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. 검증 세부사항
PREMISE 이상의 validationGranularity가 허용되지만 경우에 따라 ROUTE가 여전히 배송 가능한 주소를 나타냅니다.
2. 기타 신호
고품질 주소에 관한 확인 결과는 다음 사항도 제공해야 합니다.
- 대체된 데이터 없음. 이 경우는
hasReplacedComponents: FALSE입니다. - 추론된 구성요소 없음. 이 경우는
hasInferredComponents: FALSE입니다.
3. 미국 주소 신호
미국 주소에만 적용되는 특정 필드는 배송할 수 있는 고품질 주소를 나타냅니다. 허용되는 미국 주소는 다음과 같습니다.
dpvConfirmation
|
Y
|
|---|