기본 주소 확인 응답 이해

Address Validation API 응답에는 다음과 같은 최상위 속성이 포함됩니다.

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // The geocode generated for the input address.
  "geocode": {},
  // Information indicating if the address is a business, residence, etc.
  "metadata": {},
  // Information about the address from the US Postal Service
  // ("US" and "PR" addresses only).
  "uspsData": {},
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

verdict 속성

verdict 속성은 주소 유효성 검사 결과를 요약하며 주소 확인 로직을 빌드할 때 평가할 첫 번째 속성이어야 합니다. 이 속성은 출력 주소의 품질에 따라 다양한 필드를 반환할 수 있습니다. 예를 들어 다음은 양질의 주소의 verdict 속성을 보여줍니다. 이 속성은 이 특정 요청에 대해 다음 필드를 반환합니다.

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

다음 섹션에서는 verdict 속성의 모든 필드를 요약합니다.

참조 가이드에서 Verdict 를 참고하세요.

주소의 세분성

주소 세분성은 주소 또는 지오코드의 구체성을 결정하는 데 사용되는 세부정보 수준을 나타냅니다. validationGranularity 응답의 주소 구체성은 주소를 배송할 수 있는지 여부를 나타내는 주요 신호입니다.

verdict 속성은 다음과 같은 세분성 신호를 반환합니다.

  • inputGranularity — Maps JavaScript API의 Address Validation으로 전송된 주소에서 캡처된 세부정보 수준을 설명합니다. 요청의 주소 세부정보 수준은 유효성 검사 응답의 주소 세부정보 수준에 영향을 미칩니다. 예를 들어 PREMISE 수준 미만의 inputGranularity가 있는 주소는 일반적으로 PREMISE 수준의 validationGranularity를 생성하지 않습니다.
  • validationGranularity — Maps JavaScript API의 Address Validation에서 주소의 유효성을 완전히 검사할 수 있는 세분성 수준입니다. 대부분의 경우 a 세분성 수준이 PREMISE 또는 SUB_PREMISE이면 배송 가능성이 높은 양질의 주소 임을 나타냅니다.
  • geocodeGranularity — 주소와 연결된 지오코드의 세부정보 수준을 설명합니다. 예를 들어 Google 기록은 아파트 번호의 존재를 나타낼 수 있지만 대규모 아파트 단지 내에서 해당 특정 아파트의 정확한 위치는 나타내지 않을 수 있습니다. 이 경우 validationGranularity는 SUB_PREMISE이지만 geocodeGranularity는 PREMISE입니다.
참조 가이드에서 세분성 을 참고하세요.

주소의 완전성

verdict는 addressComplete 속성을 고품질 주소의 신호로 반환합니다. 즉, 누락되거나 해결되지 않았거나 예상치 못한 구성요소가 없다는 의미입니다.

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

주소에 누락되거나 해결되지 않았거나 예상치 못한 구성요소가 있는 경우 필드가 false로 설정됩니다.

참조 가이드의 Verdict 및 Address에서 addressComplete를 참고하세요.

주소 품질

가능한 여러 필드는 주소 구성요소의 문제 또는 추론되거나 누락된 주소 구성요소와 같은 주소 구성요소의 조정을 나타냅니다. 예를 들어 다음 verdict 속성은 확인되지 않은 구성요소와 누락된 addressComplete 필드가 있는 주소를 나타냅니다.

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
참조 가이드에서 Verdict 를 참고하세요.

가능한 다음 작업

possibleNextAction verdict 필드는 API 응답의 해석 요약을 제공하며, 잠재적인 후속 조치를 결정하는 데 도움이 됩니다. 이 필드는 API 응답의 다른 필드에서 파생되며 주소 정확성 또는 배송 가능성을 보장하는 것으로 간주해서는 안 됩니다.

address 및 addressComponent 속성

address 속성은 요청에 제공된 처리된 주소의 형식과 주소의 구성요소 수준 요약(주소의 오타가 있는 부분, 대체된 잘못된 부분, 추론된 누락된 부분 포함)을 제공합니다.

참조 가이드에서 Address를 참고하세요.

addressComponent 속성은 Maps JavaScript API의 Address Validation에서 처리한 주소의 요소 또는 구성요소의 세부 목록을 제공하는 address의 하위 구성요소입니다. API는 이름, 유형, 확인 수준별로 각 구성요소 필드를 식별합니다.

참조 가이드에서 addressComponent를 참고하세요.

geocode 속성

geocode

geocode 속성은 입력 주소와 연결된 지오코딩된 위치를 나타냅니다. 이 속성은 장소 ID와 같은 위치 자체에 관한 세부정보를 제공합니다.

참조 가이드에서 Geocode를 참고하세요.

metadata 속성

metadata

이 속성은 Maps JavaScript API의 Address Validation에서 처리한 모든 주소에 대해 채워지지 않을 수 있지만 주소가 주거, 비즈니스 또는 우체국 사서함 유형인지 나타냅니다.

Address Validation API 지원 범위 및 Address metadata 참조를 참고하세요.

uspsData 속성

이 속성은 미국 우편 주소에 유용한 정보를 제공합니다. 하지만 서비스에서 검증한 모든 주소에 대해 완전히 채워지는 것은 아닙니다. 따라서 이 속성을 주소 유효성 검사의 유일한 수단으로 사용해서는 안 되며 대신 verdict 및 address도 확인해야 합니다.

미국 주소 처리 및 USPSData 참조를 참고하세요.