유효성 검사 로직 빌드

이 문서에서는 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.

정확한 로직은 상황에 따라 다릅니다. 자세한 내용은 구현 가이드를 참고하세요. 확장 구성요소 라이브러리에 있는 이 로직의 오픈소스 구현을 사용할 수도 있습니다.

워크플로 개요

다음 표에는 시스템의 두 가지 작업이 요약되어 있습니다.

  1. 수정, 확인, 수락 동작에 따라 사용할 워크플로
  2. 응답에서 확인할 첫 번째 신호입니다. 여기에 설명된 신호는 verdict 속성에서 가져온 것으로, 확인할 유일한 신호는 아니지만 주소 품질을 나타내는 초기 지표를 제공합니다. 각 동작 유형은 조사해야 할 수 있는 추가 신호를 설명하는 이 문서의 섹션에 해당합니다.
시스템 동작
주소 수정

verdict의 응답은 제공해야 하는 중요한 누락된 정보를 나타냅니다. Address Validation API에서 반환하는 주소는 전송 가능한 품질이 아닐 수 있습니다.

워크플로

  1. 필요한 경우 주소 구성요소를 조사합니다.
  2. 고객에게 주소 문제를 해결하도록 안내합니다.
  3. 업데이트된 주소에 대한 유효성 검사를 요청합니다.
  4. (선택사항) API의 의견 엔드포인트에 요청을 보냅니다. 업데이트된 주소 처리를 참고하세요.
  5. 주소를 진행합니다.

확인 신호

다음 중 하나라도 해당하는 경우
주소 확인

verdict의 응답은 결과물 주소를 나타내지만 원래 입력을 변경했습니다. 맞춤법이 수정된 데이터 또는 확인할 수 있는 데이터를 추론합니다.

워크플로

  1. 수정 필요:
    1. 필요한 경우 주소 구성요소를 조사합니다.
    2. 업데이트된 주소의 유효성 검사를 요청합니다.
    3. (선택사항) API의 의견 엔드포인트로 요청을 보냅니다. 업데이트된 주소 처리를 참고하세요.
    4. 주소를 진행합니다.
  2. 수정할 필요 없음:
    1. (선택사항) API의 의견 엔드포인트로 요청을 보냅니다. 업데이트된 주소 처리를 참고하세요.
    2. 주소를 진행합니다.

확인 신호

다음 사항이 모두 적용됩니다.

  • validationGranularity에 ROUTE 이상이 포함되어 있습니다. 세부사항 값을 참조하세요.
  • addressComplete는 true입니다.
  • hasInferredComponents 필드가 true입니다. 또는 hasReplacedComponents 필드가 true입니다.
주소 수락

Address Validation API 응답은 우수한 품질의 주소를 나타냅니다.

워크플로

반환된 주소로 계속 진행합니다.

확인 신호

다음 사항이 모두 적용됩니다.

  • validationGranularity에 PREMISE 이상이 포함되어 있습니다. 세부사항 값을 참고하세요.
  • addressComplete는 true입니다.
  • 추론된 구성요소 또는 대체된 구성요소가 없습니다.

구현 안내

시스템이 Address Validation API의 신호에 응답하는 방식을 설계할 때 다음 권장사항을 따르면 더 효과적인 응답 모델을 빌드하는 데 도움이 됩니다. 하지만 이는 권장사항일 뿐이므로 비즈니스 모델에 맞게 구현해야 합니다.

안내 세부정보
위험 수준

수정 메시지를 표시할지 아니면 입력된 주소를 그대로 허용할지 결정할 때 상황에 대한 허용 수준을 고려하세요.

Address Validation API는 위험 수준과 통합하여 검증 프로세스를 최적화할 수 있는 다양한 신호를 반환합니다.

예를 들어 주소에 확인되지 않은 도로 번호가 있는 경우에도 주소를 허용할 수 있습니다. 반면에 비즈니스 운영에 더 정확한 주소가 필요한 경우 사용자에게 메시지를 표시할 수 있습니다. 두 카테고리 중 하나에 속할 수 있는 예시는 주소 허용 - 예시의 미국 외 미확인 번지수를 참고하세요.
주소 허용

고객이 프롬프트에 응답하지 않는 경우 시스템에서 원래 항목을 허용하도록 하는 것이 좋습니다.

이 경우 고객이 시스템에 없는 주소를 입력했을 수도 있습니다(예: 신규 공사).
의견 보내기

주소 확인 요청을 재발행할 때 provideValidationFeedback 엔드포인트에 요청을 전송할 수도 있습니다.

이렇게 하면 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. 유효성 검사 세부사항

validationGranularity가 ROUTE 이상이면 허용되지만 PREMISE 또는 SUBPREMISE는 전송 가능성에 대한 더 강력한 신호를 제공합니다.

2. 기타 신호

고객에게 주소 항목을 확인할지 결정할 때 확인 결과는 조사할 구성요소를 결정하기 위해 다음을 제공합니다.

추론된 데이터 hasInferredComponents 필드가 true이면 API가 다른 주소 구성요소에서 가져온 정보를 채웠음을 알 수 있습니다.
교체된 데이터 hasReplacedComponents 필드가 true인 경우 API는 입력된 데이터를 주소를 유효하게 만드는 것으로 간주되는 데이터로 대체했습니다.

3. 미국 주소 신호

미국 주소에만 적용되는 특정 필드는 로직에서 고객에게 세부정보를 확인해야 함을 나타냅니다. 다음 중 하나가 적용됩니다.

dpvConfirmation S

dpvConfirmation에 관한 자세한 내용은 미국 주소 처리를 참고하세요.
응답 주소 값이 subpremise인 missingComponentType 필드를 포함합니다.

주소 확인 예

주소 수락

확인 결과 주소가 전송 가능하며 하류 프로세스에서 추가 고객 상호작용 없이 사용할 수 있다는 신뢰도가 높으면 주소를 수락합니다.

신호 수락

Address Validation API는 주소를 확인해야 하는지 알려주는 여러 신호를 제공합니다.

1. 유효성 검사 세부사항

validationGranularity가 PREMISE 이상이면 허용되지만 경우에 따라 ROUTE가 여전히 전송 가능한 주소를 나타내는 경우도 있습니다.

2. 기타 신호

고품질 주소에 대한 확인 결과는 다음을 제공해야 합니다.

  • 대체된 데이터 없음 이 경우는 hasReplacedComponents: FALSE입니다.
  • 추론된 구성요소 없음 이 경우는 hasInferredComponents: FALSE입니다.

3. 미국 주소 신호

미국 주소에만 적용되는 특정 필드는 배송할 수 있는 고품질 주소를 나타냅니다. 허용되는 미국 주소는 다음과 같습니다.

dpvConfirmation Y

dpvConfirmation에 관한 자세한 내용은 미국 주소 처리를 참고하세요.

수락 주소 예

이전
기본 응답 이해하기