주소 확인 솔루션 가이드

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

목표

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

Address Validation API를 평가하는 단계에 도달하면 테스트의 일부로 다음 가이드라인을 사용하는 것이 좋습니다.

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

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

테스트를 수행한 후에는 위의 질문에 답하고 API가 비즈니스에 적합한지 확인할 수 있습니다.

데이터 준비

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

캡처 시점의 주소를 사용합니다. 예를 들어 이커머스 결제 내에서 Address Validation을 구현하려는 경우 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

차단

ROUTE

기타

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

verdict.validationGranularity

주소의 전반적인 출력 검증을 설명합니다.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

차단

ROUTE

기타

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

verdict.hasInferredComponents

API가 구성요소를 추론했는지 여부를 나타냅니다.

참/거짓

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

verdict.hasReplacedComponents

API가 구성요소를 교체했는지 여부를 나타냅니다.

참/거짓

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

verdict.addressComplete

주소가 완전한지 여부를 나타냅니다.

참/거짓

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

address.missingComponentTypes

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

값은 표 2를 참고하세요.

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

유효한 주소 검토

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

  • verdict.validationGranularity에 PREMISE 이상이 포함되어 있습니다.
  • verdict.addressComplete은 true입니다.
  • 추론되거나 대체된 구성요소가 없습니다.

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

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

  • 수락률이 허용 가능한 수준인가요?
  • 기존 Address Validation 워크플로를 사용하는 경우 수락률이 동일하거나 더 나은가요?

예: 올바른 주소

입력된 주소

리전

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 엔지니어