Package google.maps.addressvalidation.v1

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

색인

주소 유효성 검사

주소 확인을 위한 서비스입니다.

유효성 검사 의견 제공

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

검증 시도 순서 결과에 관한 피드백 동일한 주소에 대한 일련의 유효성 검사 호출 이후에 수행하는 마지막 호출이어야 하며 트랜잭션이 완료되면 호출해야 합니다. 주소를 완전히 확인하는 데 필요한 ValidateAddress 요청의 시퀀스에 한 번만 전송해야 합니다.

주소 확인

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

주소를 확인합니다.

주소

입력에서 파싱된 주소의 세부정보입니다.

필드
formatted_address

string

주소가 있는 지역의 주소 형식 규칙에 따라 한 줄 형식의 형식으로 된 올바른 주소입니다.

postal_address

PostalAddress

우편 주소로 표시된 검증된 주소입니다.

address_components[]

AddressComponent

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

주소 구성요소는 특정한 방식으로 정렬되지 않습니다. 목록에 있는 주소 구성요소의 순서를 가정하면 안 됩니다.

missing_component_types[]

string

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

unconfirmed_component_types[]

string

address_components에 있지만 올바른 것으로 확인될 수 없는 구성요소 유형입니다. 이 필드는 편의를 위해 제공됩니다. 즉, confirmation_levelCONFIRMED가 아니거나 inferred 플래그가 true로 설정되지 않은 모든 구성요소의 유형을 찾기 위해 address_components를 반복하는 것과 동일한 내용을 제공합니다. 사용 가능한 유형 목록은 여기에서 확인할 수 있습니다.

unresolved_tokens[]

string

입력에서 확인할 수 없는 토큰입니다. 이는 주소의 유효한 부분으로 인식되지 않는 입력일 수 있습니다 (예: '123235253253 Main St, San Francisco, CA, 94105'와 같이). 확인되지 않은 토큰은 유효한 도로 번호처럼 보이지 않으므로 ["123235253253"]의 형태일 수 있습니다.

주소 구성요소

주소, 예: 거리, 도시, 주 등

필드
component_name

ComponentName

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

component_type

string

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

confirmation_level

ConfirmationLevel

구성요소가 올바르다고 확신하는 정도를 나타냅니다.

inferred

bool

구성요소가 입력의 일부는 아님을 나타내지만 주소 위치에 관해 추론했으며 전체 주소에 제공해야 한다고 생각합니다.

spell_corrected

bool

예를 들어 잘못된 순서로 표시된 두 문자를 전환하는 등 구성요소 이름의 철자가 약간 수정되었음을 나타냅니다. 이는 외관상의 변화를 나타냅니다.

replaced

bool

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

unexpected

bool

지정된 지역의 우편 주소에 있을 것으로 예상되지 않는 주소 구성요소를 나타냅니다. 입력의 일부로만 보관되었습니다.

확인 수준

확인 수준에 사용할 수 있는 서로 다른 값입니다.

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

주소 메타데이터

주소의 메타데이터입니다. Address Validation API에 전송된 모든 주소에는 metadata가 완전히 입력되지 않을 수도 있습니다.

필드
business

bool

비즈니스의 주소임을 나타냅니다. 설정하지 않으면 값을 알 수 없음을 나타냅니다.

po_box

bool

사서함 주소를 나타냅니다. 설정하지 않으면 값을 알 수 없음을 나타냅니다.

residential

bool

거주지 주소입니다. 설정하지 않으면 값을 알 수 없음을 나타냅니다.

구성요소 이름

구성요소 이름의 래퍼입니다.

필드
text

string

이름 텍스트입니다. 예를 들어 도로명은 '5번가', 도로 번호는 '1253'입니다.

language_code

string

BCP-47 언어 코드입니다. 이 이름은 구성요소 이름이 도로 번호와 같은 언어와 연결되어 있지 않은 경우 나타나지 않습니다.

지오코드

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

필드
location

LatLng

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

주소, 위도/경도 좌표 또는 플러스 코드보다 장소 ID를 사용하는 것이 좋습니다. 운전경로를 라우팅하거나 운전할 때 좌표를 사용하면 항상 해당 좌표에 가장 가까운 도로에 지점이 맞춰집니다. 이 도로는 목적지로 빠르고 안전하게 이동할 수 있는 도로가 아니며 사유지의 접근 지점과 가까울 수도 없습니다. 또한 위치를 역 지오코딩할 경우 반환된 주소가 원래 위치와 일치한다는 보장은 없습니다.

plus_code

PlusCode

location에 해당하는 더하기 코드입니다.

bounds

Viewport

지오코딩된 장소의 경계.

feature_size_meters

float

지오코딩된 장소의 크기(미터 단위)입니다. 이는 지오코딩된 위치의 대략적 척도이지만 시맨틱 의미가 아닌 실제 크기입니다.

place_id

string

이 입력에서 지오코딩하는 장소의 PlaceID입니다.

장소 ID에 관한 자세한 내용은 여기를 참고하세요.

place_types[]

string

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

PlusCode

Plus Code(http://plus.codes)는 두 가지 형식으로 된 위치 참조입니다. 14mx14m (도 중 1/8,000도) 이상을 정의하는 전역 코드와 접두어를 참조 위치로 대체하는 복합 코드입니다.

필드
global_code

string

장소의 전역(전체) 코드(예: '9FWM33GV+HQ')는 1/8000 x 1/8000도 영역(~14x14미터)을 나타냅니다.

compound_code

string

'33GV+HQ, 람베르크, 노르웨이'와 같은 장소의 복합 코드. 글로벌 코드의 접미사를 포함하고 접두사를 참조 항목의 이름이 지정된 이름으로 바꿉니다.

유효성 검사 의견 요청

유효성 검사 의견 전송 요청입니다.

필드
conclusion

ValidationConclusion

필수 항목입니다. 검증 시도 시퀀스의 결과입니다.

이 필드가 VALIDATION_CONCLUSION_UNSPECIFIED로 설정되면 INVALID_ARGUMENT 오류가 반환됩니다.

response_id

string

필수 항목입니다. 이 피드백의 대상인 응답 ID입니다. 이는 일련의 주소 유효성 검사 시도에서 첫 번째 응답의 [response_id][google.maps.addressValidation.v1.ValidateAddressRequest.response_id] 이어야 합니다.

검증 완료

주소를 확인하는 데 필요한 주소 유효성 검사 요청 시퀀스의 최종 결과

열거형
VALIDATION_CONCLUSION_UNSPECIFIED 이 값은 사용되지 않습니다. ProvideValidationFeedbackRequest.conclusion 필드가 VALIDATION_CONCLUSION_UNSPECIFIED로 설정되면 INVALID_ARGUMENT 오류가 반환됩니다.
VALIDATED_VERSION_USED Address Validation API에서 반환하는 주소 버전이 거래에 사용되었습니다.
USER_VERSION_USED 사용자가 제공한 주소의 버전이 거래에 사용되었습니다.
UNVALIDATED_VERSION_USED 마지막 유효성 검사 시도 후 입력되었지만 재확인되지 않은 주소 버전이 거래에 사용되었습니다.
UNUSED 거래가 포기되었으며 주소가 사용되지 않았습니다.

검증 유효성 검사 응답 제공

유효성 검사 의견에 대한 응답입니다.

피드백이 성공적으로 전송되면 응답이 비어 있습니다.

usps 주소

미국 주소의 USPS 표시.

필드
first_address_line

string

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

firm

string

회사명

second_address_line

string

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

urbanization

string

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

city_state_zip_address_line

string

시/도 + 우편번호

city

string

도시 이름입니다.

state

string

2자리 상태 코드입니다.

zip_code

string

우편번호(예: 10009)

zip_code_extension

string

4자리 우편번호 확장자(예: 5023)입니다.

USPS 데이터

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

필드
standardized_address

UspsAddress

USPS 표준화된 주소입니다.

delivery_point_code

string

2자리 배송 코드

delivery_point_check_digit

string

배송 지점 검사 숫자입니다. 이 번호는 기계에서 스캔한 메일의 delivery_point_barcode 끝에 추가됩니다. delivery_point_barcode, delivery_point_check_digit, postal code, ZIP+4의 숫자를 모두 더하면 10의 배수가 생성됩니다.

dpv_confirmation

string

DPV 확인에 사용할 수 있는 값입니다. 단일 문자를 반환합니다.

  • Y: 기본 전화번호와 보조 전화번호의 주소가 DPV로 확인되었습니다.
  • N: 기본 및 보조 번호 정보를 DPV에서 확인하지 못했습니다.
  • S: DPV가 기본 번호로만 확인되었으며 확인되지 않은 보조 번호 정보가 있었습니다.
  • D: 기본 번호에만 DPV가 확인되었으며 보조 번호 정보가 누락되었습니다.
dpv_footnote

string

배송 지점 유효성의 각주입니다. 각주를 동일한 문자열에 묶을 수 있습니다.

  • AA: ZIP+4 파일과 일치하는 입력 주소
  • A1: 입력한 주소가 ZIP+4 파일과 일치하지 않음
  • BB: DPV와 일치 (모든 구성요소)
  • CC: 보조 번호가 일치하지 않음 (존재하지만 잘못됨)
  • N1: 고층 주소에 보조 전화번호가 없음
  • M1: 기본 번호가 없음
  • M3: 기본 번호가 잘못됨
  • P1: 입력 주소 RR 또는 HC 상자 번호 누락
  • P3: PO, RR 또는 HC Box 번호가 잘못되었습니다.
  • F1: 군부대 주소와 일치하는 입력 주소
  • G1: 일반 배송지 주소와 일치하는 입력 주소
  • U1: 입력 주소가 고유한 우편번호와 일치함
  • PB: PBSA 레코드와 일치하는 입력 주소
  • RR: PMB 정보가 포함된 DPV 확인 주소
  • R1: PMB 정보가 없는 DPV 확인 주소
  • R7: 이동통신사 노선 R777 또는 R779 레코드
dpv_cmra

string

주소가 고객 우편을 받는 사업체 (CMRA)인지 나타냅니다. 단일 문자를 반환합니다.

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

string

빈 장소인가요? 단일 문자를 반환합니다.

  • Y: 주소가 비어 있습니다.
  • N: 주소가 비어 있지 않습니다.
dpv_no_stat

string

통계 주소가 없거나 유효한 주소인가요? 통계 주소는 계속 사용 중이지 않거나 USPS가 서비스를 제공하지 않는 주소입니다. 단일 문자를 반환합니다.

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

string

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

접두사:

  • C: 운송업체 경로 (또는 도시 경로)
  • R: 지방도
  • H: 고속도로 노선
  • B: 사서함 섹션
  • G: 일반 게재 단위
carrier_route_indicator

string

운송업체 배송비 요율 정렬 표시기입니다.

ews_no_match

bool

배송 주소는 일치할 수 있지만, EWS 파일에도 일치검색이 곧 제공될 예정이라고 표시됩니다.

post_office_city

string

주 우체국 도시입니다.

post_office_state

string

주 우체국 상태

abbreviated_city

string

도시 약칭

fips_county_code

string

FIPS 카운티 코드입니다.

county

string

카운티 이름

elot_number

string

향상된 이동선 (eLOT) 번호

elot_flag

string

eLOT 오름차순/내림차순 (A/D)

po_box_only_postal_code

bool

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

pmb_designator

string

PMB (Private Mail Box) 단위 지정자입니다.

pmb_number

string

PMB (Private Mail Box) 번호

address_record_type

string

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

  • F: FIRM입니다. 이는 주소에 사용할 수 있는 가장 정확한 일치 수준인 Firm Record와 일치합니다.
  • G: 일반 배송. 일반 게재 레코드와 일치합니다.
  • H: 건물/아파트입니다. 건물 또는 아파트 기록과 일치합니다.
  • P: 사서함 사서함과 일치합니다.
  • R: 5차 도로 또는 고속도로 계약: 시골 도로 또는 고속도로 계약 기록과 일치하며, 둘 다 연결된 박스 번호 범위가 있을 수 있습니다.
  • S: STREET RECORD: 유효한 기본 범위 범위를 포함하는 스트리트 레코드와 일치하는 결과입니다.
default_address

bool

기본 주소를 찾았지만 더 구체적인 주소가 있음을 나타내는 표시기

error_message

string

USPS 데이터 가져오기 오류 메시지 이는 인위적으로 생성된 주소가 감지되어 USPS 처리가 정지된 경우 채워집니다.

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

cass_processed

bool

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

주소 검사 요청

주소 확인을 위한 요청입니다.

필드
address

PostalAddress

필수 항목입니다. 유효성 검사 중인 주소입니다. 형식이 지정되지 않은 주소는 address_lines를 통해 제출해야 합니다.

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

지원되는 지역은 FAQ에서 확인할 수 있습니다.

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

Address Validation API는 recipientsorganization의 값을 무시합니다. 이러한 필드의 모든 값이 삭제되며 반환되지 않습니다. 이를 설정하지 마세요.

previous_response_id

string

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

enable_usps_cass

bool

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

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

주소 확인 응답

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

필드
result

ValidationResult

주소 유효성 검사 결과

response_id

string

이 응답을 식별하는 UUID입니다. 주소를 재검증해야 하는 경우 이 UUID가 새 요청에 포함되어야 합니다.

ValidationResult

주소 유효성 검사 결과

필드
verdict

Verdict

전체 결과 플래그

address

Address

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

geocode

Geocode

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

metadata

AddressMetadata

기타 배송 가능성 관련 정보 Address Validation API에 전송된 모든 주소에는 metadata가 완전히 입력되지 않을 수도 있습니다.

usps_data

UspsData

USPS에서 제공하는 추가 제공 항목 플래그입니다. USPR 리전에서만 제공됩니다.

결과

주소 유효성 검사 결과 및 지오코딩의 대략적인 개요입니다.

필드
input_granularity

Granularity

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

예를 들어 입력 주소에 특정 아파트 번호가 포함된 경우 여기서 input_granularitySUB_PREMISE입니다. 데이터베이스에 입력된 아파트 호수와 일치하지 않거나 아파트 호수가 잘못된 경우 validation_granularityPREMISE 이하일 가능성이 높습니다.

validation_granularity

Granularity

API가 주소를 완전히 검증할 수 있는 세부사항 수준입니다. 예를 들어 PREMISEvalidation_granularity는 대략적 수준 PREMISE 이상의 모든 주소 구성요소를 검증할 수 있음을 나타냅니다.

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

geocode_granularity

Granularity

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

경우에 따라 위의 validation_granularity과 다를 수 있습니다. 예를 들어 Google 데이터베이스에는 아파트의 존재 여부를 기록할 수 있지만 큰 아파트 단지 내에 있는 아파트의 정확한 위치는 없습니다. 이 경우 validation_granularitySUB_PREMISE이지만 geocode_granularityPREMISE입니다.

address_complete

bool

확인되지 않은 토큰, 예기치 않은 주소 구성요소 또는 누락된 주소 구성요소가 없는 경우 주소가 완전한 것으로 간주됩니다. 자세한 내용은 missing_component_types, unresolved_tokens 또는 unexpected 필드를 참고하세요.

has_unconfirmed_components

bool

하나 이상의 주소 구성요소를 분류하거나 확인할 수 없습니다. 자세한 내용은 google.maps.addressvalidation.v1.Address.address_components 페이지를 참고하세요.

has_inferred_components

bool

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

has_replaced_components

bool

하나 이상의 주소 구성요소가 대체되었습니다. 자세한 내용은 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 다른 모든 세분화는 게재할 수 없기 때문에 버케팅됩니다.