이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Address Validation API를 사용하여 대량의 주소 처리

목표

개발자는 품질이 좋지 않을 수 있는 고객 주소가 포함된 데이터 세트를 종종 사용합니다. 고객 신원 확인부터 배송 등에 이르는 사용 사례에는 주소가 올바른지 확인해야 합니다.

Address Validation API는 주소를 확인하는 데 사용할 수 있는 Google Maps Platform의 제품입니다. 그러나 한 번에 하나의 주소만 처리합니다. 이 문서에서는 API 테스트부터 일회성 및 반복 주소 검증에 이르기까지 다양한 시나리오에서 대용량 주소 검증을 사용하는 방법을 살펴봅니다.

사용 사례

이제 대용량 주소 검증이 유용한 사용 사례를 살펴보겠습니다.

테스트

수천 개의 주소를 실행하여 Address Validation API를 테스트하려는 경우가 많습니다. 쉼표로 구분된 값 파일에 주소가 있으며 주소의 품질을 확인하고자 할 수 있습니다.

주소의 일회성 유효성 검사

Address Validation API에 온보딩하는 동안 사용자 데이터베이스와 비교하여 기존 주소 데이터베이스의 유효성을 검사하려고 합니다.

주소 반복 확인

다음과 같이 주소를 반복적으로 확인해야 하는 시나리오가 많습니다.

고객 가입, 주문 세부정보, 배송 일정 등 하루 동안 캡처된 세부정보를 얻기 위해 주소의 유효성을 검사하는 작업이 예약되어 있을 수 있습니다.
영업에서 마케팅에 이르기까지 여러 부서의 주소가 포함된 데이터 덤프를 받을 수 있습니다. 주소를 수신하는 새 부서에서 사용하기 전에 주소를 검증하려고 하는 경우가 많습니다.
설문조사나 다양한 프로모션 과정에서 주소를 수집할 수 있으며 이후 온라인 시스템에서 업데이트할 수 있습니다. 시스템에 입력할 때 주소가 올바른지 확인하고자 합니다.

기술 심층 정보

이 문서에서는 다음과 같이 가정합니다.

고객 데이터베이스의 주소 (예: 고객 세부정보가 있는 데이터베이스)를 사용하여 Address Validation API를 호출합니다.
데이터베이스의 개별 주소에 대해 유효성 플래그를 캐시할 수 있습니다.
개별 고객이 로그인하면 Address Validation API에서 유효성 플래그를 검색합니다.

프로덕션 사용을 위한 캐싱

Address Validation API를 사용할 때 API 호출의 응답의 일부를 캐시해야 하는 경우가 많습니다. 서비스 약관에 따라 캐시할 수 있는 데이터가 제한되지만 Address Validation API를 통해 캐시될 수 있는 모든 데이터는 사용자 계정에 대해 캐시되어야 합니다. 즉, 데이터베이스에서 주소 또는 주소 메타데이터를 사용자의 이메일 주소 또는 다른 기본 ID와 비교하여 캐시해야 합니다.

대용량 주소 검증 사용 사례의 경우 데이터 캐싱은 11.3항에 설명된 Address Validation API 서비스별 약관을 따라야 합니다. 이 정보를 바탕으로 사용자의 주소가 잘못된 것인지 여부를 판단할 수 있으며, 이 경우 사용자는 다음 번에 애플리케이션과 상호작용할 때 수정된 주소를 입력하라는 메시지가 표시됩니다.

Verdict 객체의 데이터
- inputGranularity
- validationGranularity
- geocodeGranularity
- addressComplete
- hasUnconfirmedComponents
- hasInferredComponents
- hasReplacedComponents
AddressComponent 객체의 데이터
- confirmationLevel
- inferred
- spellCorrected
- replaced
- unexpected

실제 주소에 대한 정보를 캐시하려면 사용자의 동의가 있는 경우에만 데이터를 캐시해야 합니다. 이렇게 하면 사용자가 특정 서비스에서 주소를 저장하는 이유를 잘 알 수 있으며 주소 공유 약관에도 동의하는 것으로 간주됩니다.

사용자 동의의 예로는 결제 페이지의 전자상거래 주소 양식과의 직접적인 상호작용이 있습니다. 패키지를 배송할 목적으로 주소를 캐시하고 처리한다는 점을 이해하고 있습니다.

사용자의 동의가 있으면 응답에서 formattedAddress 및 기타 주요 구성요소를 캐시할 수 있습니다. 하지만 헤드리스 시나리오에서는 주소 검증이 백엔드에서 이루어지므로 사용자가 동의할 수 없습니다. 따라서 이 헤드리스 시나리오에서는 매우 제한된 정보를 캐시할 수 있습니다.

응답 이해하기

Address Validation API 응답에 다음 마커가 포함되어 있으면 입력 주소가 결과물 품질임을 확신할 수 있습니다.

결과 객체의 addressComplete 마커는 true입니다.
결과 객체의 validationGranularity은 PREMISE 또는 SUB_PREMISE입니다.
AddressComponent 중 어떤 것도 다음으로 표시되지 않습니다.
- Inferred(참고: inferred=true는 addressComplete=true인 경우 발생할 수 있음)
- spellCorrected
- replaced
- unexpected
confirmationLevel: AddressComponent의 확인 수준이 CONFIRMED또는UNCONFIRMED_BUT_PLAUSIBLE로 설정됩니다.

API 응답에 위의 마커가 포함되어 있지 않으면 입력 주소의 품질이 낮기 때문일 수 있으며, 데이터베이스에 플래그를 캐시하여 이를 반영할 수 있습니다. 캐시된 플래그는 전체 주소의 품질이 낮다는 것을 나타내는 반면, 맞춤법 수정됨과 같은 더 자세한 플래그는 주소 품질 문제의 특정 유형을 나타냅니다. 고객이 다음에 품질이 좋지 않다고 표시된 주소와 상호작용할 때 기존 주소로 Address Validation API를 호출할 수 있습니다. Address Validation API는 수정된 주소를 반환하며, 이 주소는 UI 메시지를 통해 표시할 수 있습니다. 고객이 형식이 지정된 주소를 수락하면 응답에서 다음을 캐시할 수 있습니다.

formattedAddress
postalAddress
addressComponent componentNames 또는
UspsData standardizedAddress

헤드리스 주소 유효성 검사 구현

위 내용을 바탕으로 다음 단계를 따르세요.

비즈니스상의 이유로 Address Validation API의 응답 중 일부를 캐시해야 하는 경우가 많습니다.
하지만 Google Maps Platform의 서비스 약관에 따라 캐시할 수 있는 데이터가 제한됩니다.

다음 섹션에서는 서비스 약관을 준수하고 대량 주소 확인을 구현하는 방법에 대한 2단계 프로세스를 설명합니다.

1단계:

첫 번째 단계에서는 기존 데이터 파이프라인에서 대용량 주소 유효성 검사 스크립트를 구현하는 방법을 살펴보겠습니다. 이 프로세스를 통해 Address Validation API 응답의 특정 필드를 서비스 약관을 준수하는 방식으로 저장할 수 있습니다.

다이어그램 A: 다음 다이어그램은 대용량 주소 유효성 검사 로직으로 데이터 파이프라인을 개선하는 방법을 보여줍니다.

alt_text

서비스 약관에 따라 헤드리스 방식으로 주소를 확인할 때 addressComplete,validationGranularity and validationFlags를 캐시할 수 있습니다 .
고객 데이터베이스의 특정 UserID에 대해 addressComplete,validationGranularity and validationFlags, PlaceID를 캐시할 수 있습니다.

따라서 이 구현 단계에서는 UserID에 대해 위에 언급된 필드를 캐시합니다.

자세한 내용은 실제 데이터 구조를 참조하세요.

2단계:

1단계에서는 입력 데이터 세트의 일부 주소가 품질이 좋지 않을 수 있다는 피드백을 수집했습니다. 다음 단계에서는 신고된 주소를 가져와 사용자에게 표시하고 저장된 주소를 수정하는 데 대한 동의를 얻습니다.

다이어그램 B: 이 다이어그램은 사용자 동의 흐름의 엔드 투 엔드 통합이 어떻게 이루어지는지 보여줍니다.

alt_text

사용자가 로그인할 때 먼저 다음과 같은 유효성 검사 플래그가 시스템에 캐시되었는지 확인합니다.
- addressComplete이(가) true입니다.
- validationGranularity가 PREMISE 또는 SUB_PREMISE이 아님
- validationFlags은(는) inferred,spellCorrected,replaced,unexpected입니다.
  - 플래그가 없으면 기존 캐시된 주소의 품질이 우수하다고 확신하므로 이 주소를 사용할 수 있습니다.
플래그가 있는 경우 사용자에게 주소 수정/업데이트를 위한 UI를 제공해야 합니다.
업데이트되거나 캐시된 주소로 Address Validation API를 다시 호출하고 사용자가 확인할 수 있도록 수정된 주소를 제공할 수 있습니다.
주소의 품질이 좋으면 Address Validation API가 formattedAddress를 반환합니다.
수정된 경우 사용자에게 해당 주소를 제시하거나, 수정된 내용이 없는 경우 조용히 수락할 수 있습니다.
사용자가 수락하면 데이터베이스에 formattedAddress를 캐시할 수 있습니다.

2단계를 구현하는 유사 코드:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

결론

대용량 주소 검증은 많은 애플리케이션에서 접할 수 있는 일반적인 사용 사례입니다. 이 문서에서는 Google Maps Platform 서비스 약관을 준수하는 솔루션을 구현하는 방법에 대한 몇 가지 시나리오와 설계 패턴을 설명합니다.

또한 GitHub에 오픈소스 라이브러리로서 대용량 주소 검증의 참조 구현을 작성했습니다. 대용량 주소 검증을 사용해 빠르게 빌드하려면 확인해 보세요. 또한 다양한 시나리오에서 라이브러리를 사용하는 방법에 관한 디자인 패턴에 관한 도움말을 참고하세요.

다음 단계

신뢰할 수 있는 주소로 결제, 배송, 운영 개선 백서를 다운로드하고 주소 확인으로 결제, 배송, 운영 개선 웹 세미나를 확인하세요.

권장 추가 자료:

기여자

이 도움말은 Google에서 유지관리합니다. 이 글은 다음 도움을 주신 분들이 처음 작성했습니다.
수석 저자:

헨릭 밸브 | 솔루션 엔지니어
토마스 앙글라렛 | 솔루션 엔지니어
사르탁 강굴리 | 솔루션 엔지니어