주소 유효성 검사 솔루션 선택

테스트 단계의 대략적인 개요를 보여주는 흐름 다이어그램

목표

주소 검증은 다양한 사용 사례에 가치를 제공하며, 테스트 결과의 원시 품질 외에도 살펴볼 만한 주요 고려사항이 있습니다. 예를 들어 Place Autocomplete 및 지도와 같은 사용자 흐름에서 호환되는 제품의 전체적인 보기, 지역별 사용 가능 여부, 엔터프라이즈 신뢰 및 안정성을 들 수 있습니다.

Address Validation API를 평가할 때는 다음 가이드라인을 사용하여 테스트하는 것이 좋습니다.

이 테스트의 목표는 다음과 같습니다.

  1. Address Validation API가 사용 사례에 적합한지 확인합니다.
  2. Address Validation API가 다음과 같은 솔루션 요구사항을 충족하는지 확인합니다.
    • 고품질 주소를 식별합니다.
    • 품질이 낮은 입력사항을 해결하기 위한 알림
    • 추론, 대체, 맞춤법 수정을 포함하여 주소 데이터를 수정합니다.
    • 배송을 위한 형식이 지정된 주소를 제공합니다.
    • 누락되거나 잘못된 하위 부속 건물 데이터에 대한 알림 (미국만 해당)
  3. API 구현으로 측정 가능한 이점을 얻을 수 있는지 확인합니다.

테스트를 실행한 후 위 질문에 답변하고 API가 비즈니스에 적합한지 판단할 수 있습니다.

데이터 준비

기존 주소 데이터 샘플을 대상으로 테스트를 실행해야 합니다. 테스트에 사용할 데이터를 직접 선택하지 말고 운영 중인 지역을 대표하는 무작위 샘플을 선택하세요. 즉, 미국과 영국에서 모두 운영하지만 비즈니스의 70% 가 영국에서, 30% 가 미국에서 이루어지는 경우 샘플은 이러한 분할을 반영해야 합니다.

캡처 지점의 주소를 사용합니다. 예를 들어 전자상거래 결제 내에서 주소 유효성 검사를 구현하려는 경우 Address Validation API를 구현하여 대체될 수 있는 기존 처리가 실행되기 전에 고객이 양식에 입력한 주소를 사용합니다.

테스트에 사용할 샘플 크기를 약 5,000~10,000개 레코드로 준비합니다.

API 호출

섹션 기본 요건: 주소 유효성 검사 요청을 보내는 방법을 이해합니다.

데이터를 준비한 후에는 API에 대해 각 주소 레코드를 실행해야 합니다.

API를 호출하는 방법에 관한 안내는 Address Validation API 문서를 참고하세요. Address Validation API를 사용하여 대량의 주소를 처리하는 권장사항을 설명하는 도움말도 있습니다.

이 단계의 결과는 각 주소 레코드에 대해 API에서 출력한 데이터여야 합니다. 그런 다음 결과를 분석하여 사용 사례에 적합한 API인지 확인할 수 있습니다. 스프레드시트, 데이터베이스 또는 다른 도구를 사용하는지 여부는 개발자마다 다릅니다.

결과 검토하기

섹션 기본사항: 유효성 검사 응답을 처리하는 방법, 특히 수정, 확인, 수락의 개념을 이해합니다.

이 섹션에서는 솔루션 적합성을 평가하기 위해 분석할 수 있는 출력 시나리오를 설명합니다.

이 문서에서 설명하는 주요 API 필드 개요

응답 데이터

정의

평가 방법

어떤 도움이 되나요?

verdict.inputGranularity

주소의 입력 세분성을 설명합니다.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

차단

경로

기타

입력한 주소에 유효할 수 있을 만큼 충분한 데이터가 있는지 확인할 수 있습니다.

verdict.validationGranularity

주소의 전반적인 출력 유효성 검사를 설명합니다.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

차단

경로

기타

API의 출력에서 전체 주소 품질을 확인할 수 있습니다.

verdict.hasInferredComponents

API가 구성요소를 추론했는지 신호를 보냅니다.

참/거짓

API는 데이터를 추론할 수 있는 위치에 누락된 구성요소를 추가할 수 있습니다. 예를 들어 주 코드가 누락된 경우

verdict.hasReplacedComponents

API가 구성요소를 교체했는지 신호를 보냅니다.

참/거짓

API는 일부 시나리오에서 잘못된 구성요소를 올바른 데이터로 대체할 수 있습니다.

verdict.addressComplete

주소가 완료되었음을 나타냅니다.

참/거짓

API에서 출력 주소에 필요한 모든 구성요소가 있다고 판단하면 이 값은 true입니다.

address.missingComponentTypes

주소에 구성요소가 누락된 경우 경고를 보내는 신호입니다.

표 2에서 값을 확인하세요.

불완전한 주소에서 누락된 구성요소를 강조 표시합니다.

유효한 주소 검토

API에서 반환된 데이터를 정렬하여 시스템에서 유효한 것으로 허용하는 주소 집합을 확인합니다. API에서 확인해야 하는 주요 신호는 다음과 같습니다.

  • verdict.validationGranularity에는 PREMISE 이상이 포함됩니다.
  • verdict.addressComplete은 true입니다.
  • 추론된 구성요소 또는 대체된 구성요소가 없습니다.

자세한 내용은 주소 수락을 참고하세요.

이 연습의 출력은 시스템에서 유효한 것으로 허용하는 주소 데이터의 하위 집합이어야 합니다. 이 시점에서 다음을 확인할 수 있습니다.

  • 수락 비율이 허용되나요?
  • 기존 주소 유효성 검사 워크플로를 사용하는 경우 수락률이 비슷하거나 더 우수한가요?

예: 유효한 주소

입력된 주소

리전

76 Buckingham Palace Road, London SW1W 9TQ

영국

결과

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

잘못된 주소 검토

이 단계에서는 잘못된 것으로 표시된 일부 주소 데이터를 수동으로 검토하고 Address Validation API를 사용하지 않고도 잘못된 주소로 인해 다운스트림 문제가 발생할 수 있는지 확인할 수 있습니다.

API에서 반환된 데이터를 정렬하여 시스템에서 잘못된 것으로 표시할 주소 집합을 확인합니다. API에서 확인해야 하는 주요 신호는 다음과 같습니다.

  • verdict.validationGranularity: 위험 수준에 따라 OTHER 또는 ROUTE로 설정됩니다.
  • verdict.addressComplete은 false입니다.

자세한 내용은 주소 수정을 참고하세요.

이 연습의 출력은 시스템에서 잘못된 것으로 표시할 주소 데이터의 하위 집합이어야 합니다. 이 시점에서 잘못된 비율을 허용할지 결정할 수 있습니다.

주소를 잘못된 것으로 표시하는 것은 Address Validation API의 핵심 기능이며 잘못된 것으로 표시된 주소의 비율이 높다고 해서 반드시 API에 나쁜 영향을 미치는 것은 아닙니다. API는 주소에 문제가 있다는 정보를 제공합니다. 이렇게 하면 다운스트림에서 문제가 발생하기 전에 오류를 더 일찍 포착하여 워크플로의 효율성을 높일 수 있습니다.

예: 잘못된 주소

입력된 주소

리전

21 45 40th street

미국

결과

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

누락되거나 확인되지 않은 구성요소 검토

이 단계에서는 누락되거나 확인되지 않은 구성요소도 검토할 수 있습니다. 이는 반환의 Address 객체의 일부입니다. 두 필드는 missingComponentTypes 및 unconfirmedComponentTypes입니다.

이러한 필드를 사용하여 API에서 주소를 잘못된 것으로 표시한 이유를 감지하고 잘못된 특정 필드를 데이터 수집 지점으로 다시 제공하여 주소가 유효하도록 하는 올바른 정보를 수집하세요. 이는 API가 데이터 품질에 관한 구체적인 정보를 제공하여 가치를 제공하는 방법입니다.

예: 누락된 확인되지 않은 구성요소

입력된 주소

리전

Fake St, New York, NY 10011

미국

결과

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

누락되거나 확인되지 않은 구성요소

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

수정된 주소 검토

Address Validation API는 입력 데이터를 수정하여 잘못되었을 수 있는 주소 입력을 가져와 유효한 주소 데이터를 출력할 수 있습니다. 이는 API가 가치를 부여하는 한 가지 방법이며 이를 테스트의 일부로 캡처하는 것이 중요합니다.

확인해야 할 주요 신호는 다음과 같습니다.

  • addressComponents에서 inferred, replaced 또는 spellCorrected가 true로 설정됨
  • verdict.hasInferredComponents 또는 verdict.hasReplacedComponents가 true로 설정됨

자세한 내용은 주소 확인을 참고하세요.

이 연습의 출력은 API에서 수정이 적용된 주소 데이터의 하위 집합이어야 합니다.

이 데이터의 일부를 수동으로 검토하여 API가 다운스트림 워크플로의 문제를 줄이는 데이터를 수정하고 있는지 확인할 수 있습니다.

예: 수정된 주소

입력된 주소

리전

76 Bruckingm Palace Road, London SW1W 9TQ

영국

경로 addressComponent

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[미국만 해당] 하위 부지 데이터가 누락되거나 잘못된 주소 검토

Address Validation API는 미국 주소의 하위 부속건물이 누락되었거나 잘못되었는지 확인할 수 있습니다.

확인해야 할 주요 신호는 다음과 같습니다.

  • Address 객체에서 다음을 실행합니다.
    • unconfirmedComponentTypes 포함 subpremise
    • missingComponentTypes 포함 subpremise
  • UspsData 객체에서 다음을 실행합니다.
    • dpvConfirmation가 D임 (하위 문장 누락됨)
    • dpvConfirmation은 S입니다 (하위 전제가 확인되지 않음).

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

이 테스트는 아파트 번호와 같이 하위 건물이 누락되거나 잘못된 데이터에 문제가 있는지 보여줍니다. 이로 인해 특히 전송 사용 사례에서 다운스트림 문제가 발생할 수 있습니다. Address Validation API는 이를 조기에 식별하여 워크플로에 가치를 더할 수 있으므로 수정된 데이터를 수집하는 단계를 구현할 수 있습니다.

예: 하위 전제가 누락됨

입력된 주소

리전

111 8th Avenue, Manhattan, NY 10011

미국

구성요소 누락

"missingComponentTypes": [
    "subpremise"
]

USPS 데이터 DPV 확인

"dpvConfirmation": "D"

[미국만 해당] USPS standardizedAddress 검토

Address Validation API는 미국 주소의 USPS 표준화된 주소도 반환합니다. 이는 배송물 라벨에 USPS 형식의 주소를 인쇄해야 하는 경우에 특히 중요합니다.

UspsAddress를 검토하여 이 데이터를 확인하고 워크플로에 가치를 더하는지 확인할 수 있습니다.

예: USPS 표준화된 주소

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

결론

테스트 시작 - 지금 바로 Address Validation API 테스트를 시작하여 정확한 주소 데이터를 확보하고, 고객 경험을 개선하며, 비즈니스 운영을 간소화하세요. 위에 설명된 테스트 시나리오를 따르면 Address Validation API가 워크플로에 가치를 제공할지 판단하는 데 필요한 정보를 얻을 수 있습니다.

추가 자료:

참여자

헨릭 발브 | DevX 엔지니어