Method: validateAddress

주소를 확인합니다.

HTTP 요청

POST https://addressvalidation.googleapis.com/v1:validateAddress

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
필드
address

object (PostalAddress)

필수 항목입니다. 확인할 주소입니다. 형식이 지정되지 않은 주소는 addressLines를 통해 제출해야 합니다.

이 입력의 필드 총 길이는 280자(영문 기준) 이하여야 합니다.

지원되는 리전은 여기에서 확인할 수 있습니다.

입력 주소의 languageCode 값은 나중에 사용할 수 있도록 예약되어 있으며 오늘 무시됩니다. 확인된 주소 결과는 시스템에서 식별한 지정된 주소의 기본 언어를 기반으로 채워집니다.

Address Validation API는 recipients 및 organization의 값을 무시합니다. 이러한 필드의 값은 삭제되고 반환되지 않습니다. 설정하지 마세요.
previousResponseId

string

첫 번째 주소 유효성 검사 요청의 경우 이 필드는 비어 있어야 합니다. 단일 주소를 완전히 검증하는 데 더 많은 요청이 필요한 경우(예: 사용자가 초기 검증 후 변경한 사항을 다시 검증해야 하는 경우) 각 후속 요청은 검증 시퀀스의 첫 번째 응답에서 responseId로 이 필드를 채워야 합니다.
enableUspsCass

boolean

USPS CASS 호환 모드를 사용 설정합니다. 이는 google.maps.addressvalidation.v1.ValidationResult의 google.maps.addressvalidation.v1.ValidationResult.usps_data 필드에만 영향을 미칩니다. 참고: 푸에르토리코의 주소에 대해 USPS CASS가 사용 설정된 요청의 경우 address의 google.type.PostalAddress.region_code를 'PR'로 제공하거나 address의 google.type.PostalAddress.administrative_area를 'Puerto Rico'(대소문자 구분 안 함) 또는 'PR'로 제공해야 합니다.

구성요소화된 address를 사용하거나 첫 번째 줄에 번지수와 이름이 포함되고 두 번째 줄에 도시, 주, 우편번호가 포함된 google.type.PostalAddress.address_lines를 2개 이상 지정하는 것이 좋습니다.
languageOptions

object (LanguageOptions)

선택사항입니다. 미리보기: 이 기능은 미리보기(GA 이전) 버전입니다. GA 이전 제품과 기능은 지원이 제한될 수 있으며, GA 이전 제품과 기능이 변경된 경우 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 및 서비스에는 Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Address Validation API가 응답에 추가 정보를 포함하도록 지원합니다.
sessionToken

string

선택사항입니다. 결제 목적으로 자동 완성 세션을 식별하는 문자열입니다. URL 및 파일 이름에 안전한 base64 문자열이어야 하며 길이는 최대 36자(영문 기준)여야 합니다. 그렇지 않으면 INVALID_ARGUMENT 오류가 반환됩니다.

세션은 사용자가 자동 완성 쿼리를 실행하면 시작되고 장소를 선택하고 Place Details 또는 Address Validation을 호출하면 종료됩니다. 세션마다 여러 개의 자동 완성 쿼리가 포함될 수 있으며 하나의 장소 세부정보 또는 주소 유효성 검사 요청이 뒤따릅니다. 세션 내 각 요청에 사용되는 사용자 인증 정보는 동일한 Google Cloud 콘솔 프로젝트에 속해야 합니다. 세션이 종료되면 토큰이 더 이상 유효하지 않습니다. 앱은 세션마다 새 토큰을 생성해야 합니다. sessionToken 매개변수가 생략되거나 세션 토큰을 재사용하는 경우 세션 토큰이 제공되지 않은 것처럼 세션에 대해 요금이 청구됩니다(각 요청에 대해 별도로 요금이 청구됨).

참고: Address Validation은 자동 완성 API가 아닌 자동 완성(신규) API가 있는 세션에서만 사용할 수 있습니다. 자세한 내용은 https://developers.google.com/maps/documentation/places/web-service/session-pricing을 참고하세요.

응답 본문

주소 유효성 검사 요청에 대한 응답입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
필드
result

object (ValidationResult)

주소 유효성 검사 결과입니다.
responseId

string

이 응답을 식별하는 UUID입니다. 주소의 유효성을 다시 검사해야 하는 경우 이 UUID가 새 요청에 따라야 합니다.

PostalAddress

우편 배달 또는 수취인 주소와 같은 우편 주소를 나타냅니다. 우편 주소가 있으면 우체국이 사업장, 사서함 또는 이와 유사한 주소로 물건을 배달할 수 있습니다. 도로, 마을, 산 등 지리적 위치를 모델링하기 위한 것은 아닙니다.

일반적으로 주소는 프로세스 유형에 따라 사용자 입력을 통해 또는 기존 데이터 가져오기를 통해 만들어집니다.

주소 입력 / 수정에 관한 조언: - https://github.com/google/libaddressinput과 같이 국제화가 가능한 주소 위젯 사용) - 입력란이 사용되는 국가 이외의 국가에서는 입력란을 입력하거나 수정할 수 있는 UI 요소가 사용자에게 표시되어서는 안 됩니다.

이 스키마를 사용하는 방법에 대한 자세한 내용은 https://support.google.com/business/answer/6397478을 참고하세요.

JSON 표현 
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
필드
revision

integer

PostalAddress의 스키마 버전입니다. 0 이외의 값을 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다.
regionCode

string

선택사항입니다. 주소의 국가/지역의 CLDR 지역 코드입니다. 자세한 내용은 https://cldr.unicode.org/ 및 https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html을 참고하세요. 예: 스위스의 경우 'CH'. 지역 코드가 제공되지 않으면 주소에서 추론됩니다. 최상의 성능을 위해 아는 경우 지역 코드를 포함하는 것이 좋습니다. 리전이 일관되지 않거나 반복되면 성능이 저하될 수 있습니다. 예를 들어 addressLines에 이미 리전이 포함된 경우 이 필드에 리전 코드를 다시 입력하지 마세요. 지원되는 지역은 FAQ에서 확인할 수 있습니다.
languageCode

string

입력 주소의 언어 코드는 나중에 사용할 수 있도록 예약되어 있으므로 지금은 무시됩니다. API는 주소가 위치한 위치에 적합한 언어로 주소를 반환합니다.
postalCode

string

선택사항입니다. 주소의 우편번호입니다. 모든 국가에서 우편번호를 사용하거나 우편번호가 있어야 하는 것은 아니지만 사용되는 경우 주소 다른 부분의 추가 유효성 검사(예: 미국의 주/우편번호 유효성 검사)가 트리거될 수 있습니다.
sortingCode

string

선택사항입니다. 국가별 추가 정렬 코드입니다. 대부분의 지역에서는 사용되지 않습니다. 이 필드가 사용되는 경우 값은 'CEDEX'와 같은 문자열(선택적으로 숫자 뒤에 오는 경우(예: 'CEDEX 7')) 또는 '섹터 코드'(자메이카), '배송 지역 지표'(말라위) 또는 '우체국 지표'(예: 코트디부아르)를 나타내는 숫자만으로 구성됩니다.
administrativeArea

string

선택사항입니다. 국가 또는 지역의 우편 주소에 사용되는 최상위 행정 구역 단위입니다. 예를 들어 미국의 주, 캐나다의 주, 구소련의 주 또는 프랑스의 도가 될 수 있습니다. 구체적으로 스페인의 경우에는 광역 자치주가 아니라 주(province)입니다(예: '카탈로니아'가 아니라 '바르셀로나'). 많은 국가에서는 우편 주소에 행정 구역을 사용하지 않습니다. 예를 들어 스위스에서는 이 필드를 채우지 않은 상태로 두어야 합니다.
locality

string

선택사항입니다. 일반적으로 주소의 시/군/구 부분을 나타냅니다. 예: 미국 시, 이탈리아 코무네, 영국 포스트타운. 지역이 잘 정의되지 않거나 이 구조에 잘 맞지 않는 경우 지역을 비워 두고 addressLines를 사용합니다.
sublocality

string

선택사항입니다. 주소의 하위 지역입니다. 예를 들어 인근 지역, 자치구, 구일 수 있습니다.
addressLines[]

string

필수 항목입니다. 주소의 하위 수준을 설명하는 구조화되지 않은 주소 입력란입니다.

addressLines의 값에는 형식 정보가 없고 경우에 따라 하나의 필드에 여러 값이 포함될 수 있으므로(예: 'Austin, TX') 행 순서가 명확해야 합니다. 주소 입력란 순서는 주소의 국가/지역의 '봉투 순서'여야 합니다.

주소에 허용되는 최소 구조 표시는 addressLines에 배치된 모든 정보로 구성됩니다. regionCode이 제공되지 않으면 주소 행에서 리전이 추론됩니다.

주소 중 지역에 해당하는 부분과 행정 구역에 해당하는 부분을 추측하는 대신 addressLines만 포함된 주소를 만든 다음 지오코딩하는 것이 전혀 구조화되지 않은 주소를 처리하는 방법으로 좋습니다.
recipients[]

string

이 입력란은 설정하지 마세요. Address Validation API에서는 현재 이를 사용하지 않습니다. 현재 API는 이 필드가 설정된 요청을 거부하지 않지만 정보는 삭제되며 응답에 반환되지 않습니다.
organization

string

이 필드는 설정하지 마세요. Address Validation API는 현재 이를 사용하지 않습니다. 현재 API는 이 필드가 설정된 요청을 거부하지 않지만 정보는 삭제되고 응답에서 반환되지 않습니다.

LanguageOptions

미리보기: 이 기능은 미리보기 (GA 이전) 버전입니다. GA 이전 제품과 기능은 지원이 제한될 수 있으며, GA 이전 제품과 기능이 변경된 경우 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 및 서비스에는 Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Address Validation API가 응답에 추가 정보를 포함하도록 사용 설정합니다.

JSON 표현 
{
  "returnEnglishLatinAddress": boolean
}
필드
returnEnglishLatinAddress

boolean

미리보기: 영어로 google.maps.addressvalidation.v1.Address를 반환합니다. 자세한 내용은 google.maps.addressvalidation.v1.ValidationResult.english_latin_address를 참고하세요.

ValidationResult

주소 유효성 검사 결과입니다.

JSON 표현 
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
필드
verdict

object (Verdict)

전체 확인 결과 플래그
address

object (Address)

지오코드가 아닌 주소 자체에 관한 정보입니다.
geocode

object (Geocode)

주소가 지오코딩된 위치 및 장소에 대한 정보입니다.
metadata

object (AddressMetadata)

전송 가능성과 관련된 기타 정보 Address Validation API로 전송된 모든 주소에 대해 metadata가 완전히 채워지지 않을 수 있습니다.
uspsData

object (UspsData)

USPS에서 제공하는 추가 배송 가능 플래그입니다. US 및 PR 리전에서만 제공됩니다.
englishLatinAddress

object (Address)

미리보기: 이 기능은 미리보기(GA 이전) 버전입니다. GA 이전 제품과 기능은 지원이 제한될 수 있으며, GA 이전 제품과 기능이 변경된 경우 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 및 서비스에는 Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은 출시 단계 설명을 참조하세요.

영어로 번역된 주소입니다.

번역된 주소는 API 입력으로 재사용할 수 없습니다. 서비스는 사용자가 모국어를 사용하여 원래 제공된 주소의 유효성을 확인하거나 거부할 수 있도록 제공합니다.

주소의 일부에 영어 번역이 없는 경우 서비스는 해당 부분을 라틴 자모를 사용하는 대체 언어로 반환합니다. 대체 언어가 선택되는 방법에 대한 설명은 여기를 참조하세요. 주소의 일부에 라틴 문자를 사용하는 언어로 번역 또는 음역이 없는 경우 서비스는 주소와 연결된 현지 언어로 해당 부분을 반환합니다.

google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address 플래그를 사용하여 이 출력을 사용 설정합니다.

참고: englishLatinAddress의 google.maps.addressvalidation.v1.Address.unconfirmed_component_types 필드와 englishLatinAddress.address_components의 google.maps.addressvalidation.v1.AddressComponent.confirmation_level 필드는 채워지지 않습니다.

결과

주소 유효성 검사 결과 및 지오코드의 개략적인 개요

JSON 표현 
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
필드
inputGranularity

enum (Granularity)

입력 주소의 세부사항입니다. 이는 입력 주소를 파싱한 결과이며 유효성 검사 신호를 제공하지 않습니다. 유효성 검사 신호는 아래의 validationGranularity를 참고하세요.

예를 들어 입력 주소에 특정 아파트 동호수가 포함된 경우 여기서 inputGranularity는 SUB_PREMISE입니다. 데이터베이스의 아파트 동호수를 일치시킬 수 없거나 아파트 동호수가 잘못된 경우 validationGranularity는 PREMISE 이하일 가능성이 높습니다.
validationGranularity

enum (Granularity)

API가 주소를 완전히 확인할 수 있는 세부 수준입니다. 예를 들어 validationGranularity이 PREMISE이면 PREMISE 수준 또는 그보다 상위 수준의 모든 주소 구성요소를 검증할 수 있음을 나타냅니다.

주소 구성요소별 검증 결과는 google.maps.addressvalidation.v1.Address.address_components에서 확인할 수 있습니다.
geocodeGranularity

enum (Granularity)

geocode의 세부사항에 대한 정보입니다. 이는 지오코딩된 위치가 얼마나 대략적인지 또는 얼마나 세밀한지를 나타내는 의미론적 의미로 이해할 수 있습니다.

경우에 따라 위의 validationGranularity와 다를 수도 있습니다. 예를 들어 데이터베이스에 아파트 동호수가 있는 경우에는 기록되지만 대형 아파트 단지 내의 아파트의 정확한 위치는 없을 수 있습니다. 이 경우 validationGranularity는 SUB_PREMISE이지만 geocodeGranularity는 PREMISE입니다.
addressComplete

boolean

해결되지 않은 토큰이 없고 예상치 못한 주소 구성요소가 없거나 누락된 경우 주소가 완전한 것으로 간주됩니다. 설정하지 않으면 값이 false임을 나타냅니다. 자세한 내용은 missingComponentTypes, unresolvedTokens 또는 unexpected 필드를 참고하세요.
hasUnconfirmedComponents

boolean

하나 이상의 주소 구성요소를 분류하거나 유효성 검사할 수 없습니다. 자세한 내용은 google.maps.addressvalidation.v1.Address.address_components를 참고하세요.
hasInferredComponents

boolean

입력에 없는 주소 구성요소가 하나 이상 추론(추가)되었습니다. 자세한 내용은 google.maps.addressvalidation.v1.Address.address_components를 참고하세요.
hasReplacedComponents

boolean

주소 구성요소가 하나 이상 대체되었습니다. 자세한 내용은 google.maps.addressvalidation.v1.Address.address_components를 참고하세요.

세부사항

주소 또는 지오코드가 가질 수 있는 다양한 세부사항입니다. 주소의 세부사항을 나타내는 데 사용되는 경우 이 값은 주소가 우편 목적지를 얼마나 세분화하여 식별하는지를 나타냅니다. 예를 들어 '123 Main Street, Redwood City, CA, 94061'과 같은 주소는 PREMISE를 식별하는 반면 'Redwood City, CA, 94061'과 같은 주소는 LOCALITY를 식별합니다. 하지만 레드우드 시티의 '123 Main Street' 지오코드를 찾을 수 없는 경우 주소가 더 상세하더라도 반환된 지오코드는 LOCALITY 세분화 수준일 수 있습니다.

열거형
GRANULARITY_UNSPECIFIED 기본값 이 값은 사용되지 않습니다.
SUB_PREMISE 아파트와 같이 건물 아래 수준의 결과입니다.
PREMISE 건물 수준 결과입니다.
PREMISE_PROXIMITY 주소의 건물 수준 위치에 가까운 지오코드입니다.
BLOCK 주소 또는 지오코드는 블록을 나타냅니다. 일본과 같이 블록 수준 주소가 있는 리전에서만 사용됩니다.
ROUTE 지오코드 또는 주소는 거리, 도로, 고속도로와 같이 경로에 따라 세분화됩니다.
OTHER 결과물로 제공되지 않으므로 함께 버케팅되는 기타 모든 세부사항

주소

후처리된 주소의 세부정보입니다. 후처리에는 주소의 철자가 잘못된 부분을 수정하고, 잘못된 부분을 대체하고, 누락된 부분을 추론하는 작업이 포함됩니다.

JSON 표현 
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
필드
formattedAddress

string

후처리된 주소로, 주소가 위치한 지역의 주소 형식 지정 규칙에 따라 한 줄 주소 형식으로 지정됩니다.

참고: 이 주소의 형식이 postalAddress 필드의 주소 형식과 일치하지 않을 수 있습니다. 예를 들어 postalAddress는 항상 국가를 2자리 regionCode(예: 'US' 또는 'NZ')로 나타냅니다. 반면 이 필드는 '미국' 또는 '뉴질랜드'와 같이 더 긴 국가 이름 형식을 사용합니다.
postalAddress

object (PostalAddress)

우편 주소로 표시되는 후처리 주소입니다.
addressComponents[]

object (AddressComponent)

순서가 지정되지 않은 목록입니다. 형식이 지정되고 수정된 주소의 개별 주소 구성요소와 유효성 검사 정보 이는 개별 구성요소의 유효성 검사 상태에 관한 정보를 제공합니다.

주소 구성요소는 특정 방식으로 정렬되지 않습니다. 목록의 주소 구성요소 순서에 관해 가정하지 마세요.
missingComponentTypes[]

string

올바른 형식의 우편 주소에 있어야 하지만 입력에서 찾을 수 없고 추론할 수 없는 구성요소 유형입니다. 이 유형의 구성요소는 formattedAddress, postalAddress, addressComponents에 없습니다. 'Boulder, Colorado, 80301, USA'와 같은 입력의 경우 ['street_number', 'route']를 예로 들 수 있습니다. 사용 가능한 유형 목록은 여기에서 확인할 수 있습니다.
unconfirmedComponentTypes[]

string

addressComponents에 있지만 올바른지 확인할 수 없는 구성요소의 유형입니다. 이 필드는 편의를 위해 제공됩니다. 콘텐츠는 addressComponents를 반복하여 confirmationLevel이 CONFIRMED이 아니거나 inferred 플래그가 true로 설정되지 않은 모든 구성요소의 유형을 찾는 것과 같습니다. 사용 가능한 유형 목록은 여기에서 확인할 수 있습니다.
unresolvedTokens[]

string

입력에서 확인할 수 없는 토큰입니다. 주소의 유효한 부분으로 인식되지 않은 입력일 수 있습니다. 예를 들어 'Parcel 0000123123 & 0000456456 Str # Guthrie Center IA 50115 US'와 같은 입력의 경우 확인되지 않은 토큰은 ["Parcel", "0000123123", "&", "0000456456"]처럼 보일 수 있습니다.

AddressComponent

도로, 도시, 주와 같은 주소 구성요소를 나타냅니다.

JSON 표현 
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
필드
componentName

object (ComponentName)

이 구성요소의 이름입니다.
componentType

string

주소 구성요소의 유형입니다. 가능한 유형 목록은 표 2: 장소 서비스에서 반환하는 추가 유형을 참고하세요.
confirmationLevel

enum (ConfirmationLevel)

구성요소가 올바르다는 확실성 수준을 나타냅니다.
inferred

boolean

구성요소가 입력의 일부가 아니었지만 주소 위치를 추론했으며 전체 주소를 위해 제공되어야 한다고 판단됨을 나타냅니다.
spellCorrected

boolean

구성요소 이름의 맞춤법 오류에 대한 수정을 나타냅니다. API는 항상 한 철자 변형에서 다른 철자 변형으로의 변경사항을 신고하지는 않습니다(예: 'centre'를 'center'로 변경하는 경우). 또한 'Amphitheater Pkwy'를 'Amphitheatre Pkwy'로 변경하는 경우와 같이 일반적인 오타를 항상 표시하지는 않습니다.
replaced

boolean

구성요소의 이름이 완전히 다른 이름으로 대체되었음을 나타냅니다. 예를 들어 잘못된 우편번호가 주소에 맞는 우편번호로 대체된 경우입니다. 이는 외관상의 변경이 아니라 입력 구성요소가 다른 구성요소로 변경된 것입니다.
unexpected

boolean

지정된 지역의 우편 주소에 포함되지 않을 것으로 예상되는 주소 구성요소를 나타냅니다. 입력의 일부였기 때문에만 유지되었습니다.

ComponentName

구성요소 이름에 대한 래퍼입니다.

JSON 표현 
{
  "text": string,
  "languageCode": string
}
필드
text

string

이름 텍스트입니다. 예를 들어 도로 이름의 경우 '5번가', 번지의 경우 '1253'입니다.
languageCode

string

BCP-47 언어 코드입니다. 구성요소 이름이 언어와 연결되어 있지 않은 경우(예: 번지) 이 속성은 표시되지 않습니다.

ConfirmationLevel

확인 수준의 가능한 다양한 값입니다.

열거형
CONFIRMATION_LEVEL_UNSPECIFIED 기본값 이 값은 사용되지 않습니다.
CONFIRMED 이 구성요소가 존재하며 나머지 주소의 맥락에서 적절한지 확인할 수 있었습니다.
UNCONFIRMED_BUT_PLAUSIBLE 이 구성요소를 확인할 수는 없지만 존재할 가능성이 높습니다. 예를 들어 특정 번지수를 알 수 없는 도로의 알려진 유효한 번호 범위 내에 있는 번지수입니다.
UNCONFIRMED_AND_SUSPICIOUS 이 구성요소는 확인되지 않았으며 잘못되었을 가능성이 높습니다. 예를 들어 주소의 나머지 부분과 일치하지 않는 동네입니다.

지오코드

입력값이 지오코딩된 장소에 대한 정보를 포함합니다.

JSON 표현 
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
필드
location

object (LatLng)

입력의 지오코딩된 위치입니다.

주소, 위도/경도 좌표 또는 플러스 코드보다 장소 ID를 사용하는 것이 더 좋습니다. 경로를 찾거나 운전 경로를 계산할 때 좌표를 사용하면 항상 해당 좌표에 가장 가까운 도로에 포인트가 스냅됩니다. 목적지까지 빠르거나 안전하게 연결되는 도로가 아닐 수 있으며 숙박 시설의 진입로 근처에 있지 않을 수도 있습니다. 또한 위치를 역지오코딩할 때 반환된 주소가 원본과 일치한다고 보장할 수 없습니다.
plusCode

object (PlusCode)

location에 해당하는 Plus Code입니다.
bounds

object (Viewport)

지오코딩된 장소의 경계입니다.
featureSizeMeters

number

지오코딩된 장소의 크기입니다(미터 단위). 이 값은 지오코딩된 위치의 대략적인 위치를 측정하지만 의미론적 의미가 아닌 실제 크기로 측정합니다.
placeId

string

이 입력의 지오코딩 대상 장소의 PlaceID입니다.

장소 ID에 대한 자세한 내용은 여기를 참고하세요.
placeTypes[]

string

입력이 지오코딩된 장소의 유형입니다. 예를 들면 ['locality', 'political']입니다. 유형의 전체 목록은 여기에서 확인할 수 있습니다.

LatLng

위도/경도 쌍을 나타내는 객체로 위도(도)와 경도(도)를 나타내는 double의 쌍으로 표현됩니다. 달리 명시되지 않는 한 이 객체는 WGS84 표준을 준수해야 합니다. 값은 정규화된 범위 내에 있어야 합니다.

JSON 표현 
{
  "latitude": number,
  "longitude": number
}
필드
latitude

number

위도입니다. 범위는 [-90.0, +90.0]입니다.
longitude

number

경도입니다. 범위는 [-180.0, +180.0]입니다.

PlusCode

Plus Code(http://plus.codes)는 14mx14m(1/8000도) 이하의 직사각형을 정의하는 글로벌 코드와 접두사를 참조 위치로 대체하는 복합 코드라는 두 가지 형식의 위치 참조입니다.

JSON 표현 
{
  "globalCode": string,
  "compoundCode": string
}
필드
globalCode

string

장소의 전 세계(전체) 코드(예: '9FWM33GV+HQ')로, 1/8000도x1/8000도(약 14mx14m) 영역을 나타냅니다.
compoundCode

string

장소의 복합 코드(예: '33GV+HQ, Ramberg, Norway')로, 글로벌 코드의 접미사를 포함하고 접두사를 참조 항목의 형식이 지정된 이름으로 대체합니다.

표시 영역

대각선으로 반대되는 두 개의 low 및 high 지점으로 표시되는 위도-경도 뷰포트입니다. 표시 영역은 폐쇄된 영역으로 간주됩니다. 즉, 경계가 포함됩니다. 위도 경계는 -90도에서 90도(양 끝값 포함) 사이여야 하며 경도 경계는 -180도에서 180도(양 끝값 포함) 사이여야 합니다. 다양한 케이스에는 다음이 포함됩니다.

  • low = high이면 뷰포트는 단일 지점으로 구성됩니다.

  • low.longitude > high.longitude이면 경도 범위가 반전됩니다 (표시 영역이 180도 경도 선을 교차함).

  • low.longitude = -180도이고 high.longitude = 180도이면 표시 영역에 모든 경도가 포함됩니다.

  • low.longitude = 180도이고 high.longitude = -180도인 경우 경도 범위는 비어 있습니다.

  • low.latitude가 high.latitude보다 크면 위도 범위가 비어 있습니다.

low와 high를 모두 채워야 하며, 표시된 상자는 (위 정의에 명시된 대로) 비워둘 수 없습니다. 뷰포트가 비어 있으면 오류가 발생합니다.

예를 들어 이 표시 영역은 뉴욕시를 완전히 둘러쌉니다.

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

JSON 표현 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
필드
low

object (LatLng)

필수 항목입니다. 표시 영역의 낮은 지점입니다.
high

object (LatLng)

필수 항목입니다. 뷰포트의 최고점입니다.

AddressMetadata

주소의 메타데이터입니다. Address Validation API로 전송되는 모든 주소에 metadata가 완전히 채워지는 것은 아닙니다.

JSON 표현 
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
필드
business

boolean

비즈니스 주소임을 나타냅니다. 설정되지 않은 경우 값을 알 수 없음을 나타냅니다.
poBox

boolean

사서함 주소임을 나타냅니다. 설정되지 않은 경우 값을 알 수 없음을 나타냅니다.
residential

boolean

거주지 주소임을 나타냅니다. 설정되지 않은 경우 값을 알 수 없음을 나타냅니다.

UspsData

주소의 USPS 데이터입니다. Address Validation API로 전송된 모든 미국 또는 푸에르토리코 주소에 대해 uspsData가 완전히 채워지지 않을 수 있습니다. uspsData를 응답의 기본 부분으로 활용하는 경우 응답에 백업 주소 필드를 통합하는 것이 좋습니다.

JSON 표현 
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
필드
standardizedAddress

object (UspsAddress)

USPS 표준화된 주소
deliveryPointCode

string

2자리 배송 지점 코드
deliveryPointCheckDigit

string

배송 지점 검사 숫자입니다. 이 번호는 기계적으로 스캔된 우편물의 delivery_point_barcode 끝에 추가됩니다. delivery_point_barcode, deliveryPointCheckDigit, 우편번호, ZIP+4의 모든 자릿수를 더하면 10으로 나눠지는 숫자가 나와야 합니다.
dpvConfirmation

string

DPV 확인에 가능한 값입니다. 단일 문자를 반환하거나 값을 반환하지 않습니다.

  • N: 기본 및 보조 번호 정보가 DPV 확인에 실패했습니다.
  • D: 기본 전화번호의 DPV만 확인되었으며 보조 전화번호 정보가 누락되었습니다.
  • S: 기본 번호의 DPV만 확인되었으며 보조 번호 정보는 있지만 확인되지 않았습니다.
  • Y: 기본 번호 및 모든 보조 번호의 주소가 DPV로 확인되었습니다.
  • 비어 있음: 응답에 dpvConfirmation 값이 포함되어 있지 않으면 DPV 확인을 위해 주소가 제출되지 않은 것입니다.
dpvFootnote

string

배송지 검증의 각주입니다. 여러 각주가 동일한 문자열로 연결될 수 있습니다.

  • AA: ZIP+4 파일과 일치하는 입력 주소
  • A1: 입력 주소가 ZIP+4 파일과 일치하지 않음
  • BB: DPV에 일치(모든 구성요소)
  • CC: 보조 번호가 일치하지 않으며 필요하지 않습니다.
  • C1: 일치하지 않지만 필요한 보조 전화번호
  • N1: 고층 주소에 보조 번호가 누락됨
  • M1: 기본 번호 누락
  • M3: 기본 전화번호가 잘못됨
  • P1: 입력 주소 PO, RR 또는 HC 상자 번호 누락
  • P3: 입력한 주소의 PO, RR 또는 HC 박스 번호가 잘못되었습니다.
  • F1: 입력한 주소가 군부대 주소와 일치함
  • G1: 일반 배송지 주소와 일치하는 입력 주소
  • U1: 고유한 우편번호와 일치하는 입력 주소
  • PB: PBSA 레코드와 일치하는 입력 주소
  • RR: DPV에서 PMB 정보로 주소 확인함
  • R1: PMB 정보 없이 DPV에서 확인한 주소
  • R7: 이동통신사 경로 R777 또는 R779 레코드
  • IA: 알려진 주소가 식별됨
  • TA: 후행 알파벳을 삭제하여 일치하는 기본 번호
dpvCmra

string

주소가 고객 대신 메일을 수신하는 개인 비즈니스인 CMRA (상업용 우편물 수신소)인지 여부를 나타냅니다. 단일 문자를 반환합니다.

  • Y: 주소가 CMRA입니다.
  • N: 주소가 CMRA가 아닙니다.
dpvVacant

string

이 장소는 비어 있나요? 단일 문자를 반환합니다.

  • Y: 주소가 비어 있음
  • N: 주소가 비어 있지 않음
dpvNoStat

string

통계가 없는 주소인가요 아니면 활성 주소인가요? 지속적으로 사용되지 않거나 USPS에서 서비스를 제공하지 않는 주소는 통계 주소가 아닙니다. 단일 문자를 반환합니다.

  • Y: 주소가 활성 상태가 아닙니다.
  • N: 주소가 활성 상태입니다.
dpvNoStatReasonCode

integer

NoStat 유형을 나타냅니다. 이유 코드를 int로 반환합니다.

  • 1: IDA(내부 수신 주소) – USPS에서 직접 우편을 수신하지 않지만 우편을 수신하는 수신 주소로 배송되는 주소입니다.
  • 2: CDS - 아직 결과물이 되지 않은 주소입니다. 예를 들어 로트와 1차 번호가 결정되었지만 점유율에 대한 구조가 아직 없는 새 구획인 경우입니다.
  • 3: 충돌 - 실제로 DPV 확인을 하지 않는 주소입니다.
  • 4: CMZ(대학, 군, 기타 유형) - USPS에서 데이터에 통합한 우편번호 + 4자리 레코드입니다.
  • 5: 일반 - 배송이 이루어지지 않는 주소를 나타내며, 이 주소는 배송 가능한 주소로 집계되지 않습니다.
  • 6: 보조 정보 필요 - 주소에 보조 정보가 필요합니다.
dpvDrop

string

사이트의 단일 수신함에 메일이 전송되었음을 나타내는 플래그입니다. 단일 문자를 반환합니다.

  • Y: 우편물이 사이트의 단일 수신함으로 배달됩니다.
  • N: 우편물이 사이트의 단일 수신함에 배달되지 않습니다.
dpvThrowback

string

우편물이 상세 주소로 배달되지 않았음을 나타냅니다. 단일 문자를 반환합니다.

  • Y: 우편물이 상세 주소로 배송되지 않습니다.
  • N: 우편물이 상세 주소로 배송됩니다.
dpvNonDeliveryDays

string

메일 전송이 매일 이루어지지 않음을 나타내는 플래그입니다. 단일 문자를 반환합니다.

  • Y: 메일 전송이 매일 실행되지는 않습니다.
  • N: 메일 전송이 매일 수행되지 않는다는 표시가 없습니다.
dpvNonDeliveryDaysValues

integer

미게재일을 식별하는 정수입니다. 비트 플래그를 사용하여 쿼리할 수 있습니다. 0x40 – 일요일은 발송하지 않는 날 0x20 – 월요일은 발송하지 않는 날 0x10 – 화요일은 발송하지 않는 날 0x08 – 수요일은 발송하지 않는 날 0x04 – 목요일은 발송하지 않는 날 0x02 – 금요일은 발송하지 않는 날 0x01 – 토요일은 발송하지 않는 날
dpvNoSecureLocation

string

문에 접근할 수 있지만 보안 문제로 인해 상품을 배송하지 않겠다는 플래그입니다. 단일 문자를 반환합니다.

  • Y: 보안 문제로 인해 패키지가 남지 않습니다.
  • N: 보안 문제로 인해 택배물이 분실되지 않을 것으로 표시되지 않습니다.
dpvPbsa

string

주소가 PBSA 레코드와 일치함을 나타냅니다. 단일 문자를 반환합니다.

  • Y: 주소가 PBSA 레코드와 일치합니다.
  • N: 주소가 PBSA 레코드와 일치하지 않습니다.
dpvDoorNotAccessible

string

USPS에서 우편물을 배달하기 위해 초인종을 울릴 수 없는 주소를 나타내는 플래그입니다. 단일 문자를 반환합니다.

  • Y: 문에 접근할 수 없습니다.
  • N: 문에 접근할 수 없다는 표시가 없습니다.
dpvEnhancedDeliveryCode

string

주소에 대해 유효한 DPV 반환 코드가 두 개 이상 있음을 나타냅니다. 단일 문자를 반환합니다.

  • Y: 기본 번호 및 모든 보조 번호의 주소가 DPV로 확인되었습니다.
  • N: 기본 및 모든 보조 번호 정보가 DPV 확인에 실패했습니다.
  • S: 기본 번호에 대해서만 주소가 DPV가 확인되었으며 보조 번호 정보는 있지만 확인되지 않은 경우 또는 DPV 일치와 보조 정보를 요구하기 위해 기본 번호에서 단일 후행 알파가 삭제되었습니다.
  • D: 기본 전화번호의 DPV만 확인되었으며 보조 전화번호 정보가 누락되었습니다.
  • R: 주소가 확인되었지만 유령 경로 R777 및 R779에 할당되었으며 USPS 배송이 제공되지 않습니다.
carrierRoute

string

운송업체 경로 코드입니다. 1자리 접두사와 3자리 경로 지정자로 구성된 4자리 코드입니다.

프리픽스:

  • C: 운송업체 경로(또는 도시 경로)
  • R: 농촌 경로
  • H: 고속도로 계약 경로
  • B: 우편함 섹션
  • G: 일반 배송 단위
carrierRouteIndicator

string

운송업체 경로 요금 정렬 표시기입니다.
ewsNoMatch

boolean

배송 주소는 일치 가능하지만 EWS 파일에 정확한 일치 항목이 곧 제공된다고 표시됩니다.
postOfficeCity

string

주요 우체국 소재 도시입니다.
postOfficeState

string

기본 우체국 상태입니다.
abbreviatedCity

string

약어로 표시된 도시입니다.
fipsCountyCode

string

FIPS 카운티 코드입니다.
county

string

구/군 이름입니다.
elotNumber

string

향상된 이동 경로(eLOT) 번호입니다.
elotFlag

string

eLOT 오름차순/내림차순 플래그(A/D)
poBoxOnlyPostalCode

boolean

사서함 전용 우편번호입니다.
pmbDesignator

string

PMB (Private Mail Box) 단위 지정자.
pmbNumber

string

PMB(Private Mail Box) 번호
addressRecordType

string

입력한 주소와 일치하는 주소 레코드 유형입니다.

  • F: FIRM 이는 주소에 대해 사용할 수 있는 가장 정확한 수준인 회사 기록과 일치합니다.
  • G: 일반 배송. 일반 배송 레코드와 일치합니다.
  • H: 건물/아파트 건물 또는 아파트 레코드와 일치합니다.
  • P: 우체국 우체국. 우체국 사서함과 일치합니다.
  • R: RURAL ROUTE 또는 HIGHWAY CONTRACT: 지방 도로 또는 고속도로 계약 기록과 일치하는 것으로, 두 가지 모두 연결된 박스 번호 범위를 포함할 수 있습니다.
  • S: STREET 레코드: 유효한 기본 번호 범위가 포함된 Street 레코드와 일치합니다.
defaultAddress

boolean

기본 주소가 발견되었지만 더 구체적인 주소가 있음을 나타내는 표시기입니다.
errorMessage

string

USPS 데이터 검색 오류 메시지 인위적으로 생성된 주소가 감지되어 USPS 처리가 정지되면 이 필드에 값이 입력됩니다.

이 오류가 있으면 USPS 데이터 필드가 채워지지 않을 수 있습니다.
cassProcessed

boolean

요청이 CASS 처리되었음을 나타내는 표시기입니다.

UspsAddress

미국 주소의 USPS 표현입니다.

JSON 표현 
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
필드
firstAddressLine

string

첫 번째 주소 입력란입니다.
firm

string

회사 이름입니다.
secondAddressLine

string

두 번째 주소 입력란입니다.
urbanization

string

푸에르토리코 도시 이름입니다.
cityStateZipAddressLine

string

시/도 + 우편번호
city

string

도시 이름입니다.
state

string

2자리 주 코드.
zipCode

string

우편번호(예: 10009)
zipCodeExtension

string

4자리 우편번호 확장자(예: 5023)