Geocoding API는 주소를 좌표 및 장소 ID로 변환하고 좌표 또는 장소 ID를 주소로 변환하는 웹 서비스입니다. v4 SearchDestinations 메서드는 건물 입구, 내비게이션 지점, 건물 및 부지 윤곽선, 주변 명소와 같은 목적지 세부정보도 반환합니다.
Geocoding API: 주요 정보
- 제품: Geocoding API
- 카테고리: 장소
- 플랫폼: 웹 서비스(REST)
- 실행 위치: 서버(백엔드 코드)
- 출시 단계: GA
- 수명 주기: 활성
- 개요: Geocoding API 개요
Geocoding API: 사용 시기
다음과 같은 경우 Geocoding API를 사용하세요.
- 백엔드 서버에서 상세 주소를 위도/경도 좌표와 장소 ID로 변환해야 합니다.
- GPS 좌표 또는 알려진 장소 ID에 대한 표시 주소 또는 행정 구역(도시, 우편번호)이 필요합니다.
- 운전자 또는 배송 기사를 목적지로 안내하려면 건물 입구, 경로 지정이 가능한 내비게이션 지점 또는 건물/부지 윤곽선이 필요합니다.
- 대규모 복합 시설(공항, 쇼핑몰, 캠퍼스) 내부의 목적지를 하위 목적지 또는 주변 명소로 변환해야 합니다.
다음과 같은 경우에는 Geocoding API를 사용하지 마세요.
- 클라이언트 측 브라우저 JavaScript에서 지오코딩이 필요합니다. 노출된 API 키로 v4를 호출하면 보안 위험이 발생합니다. 대신 Maps JavaScript API를 사용하세요.
- 지오코딩된 목적지까지의 경로 또는 도착 예정 시간을 계산해야 합니다. 대신 Routes API를 사용하세요.
- Android 앱에서 내비게이션 지점 토큰에 대한 세부 경로 안내가 필요합니다. 대신 Android용 Navigation SDK를 사용하세요.
- iOS 앱에서 내비게이션 지점 토큰에 대한 세부 경로 안내가 필요합니다. 대신 iOS용 Navigation SDK를 사용하세요.
Geocoding API: 설정
- 사용 설정할 서비스:
geocoding-backend.googleapis.com - 인증: API 키, OAuth 2.0, 서비스 계정
- 시작하기: Geocoding API 설정
- 참조: Geocoding API 참조
- 가격 책정: Geocoding API 사용량 및 결제
- 정책: Geocoding API 정책
- 출시 노트: Geocoding API 출시 노트
Geocoding API: 관련 상품
- 함께 자주 사용되는 제품: Routes API, Android용 Navigation SDK, iOS용 Navigation SDK
Geocoding API: 일반적인 실수
- 문제: 필드 마스크가 없는
SearchDestinations요청은 오류와 함께 실패합니다.GeocodeAddress,GeocodeLocation,GeocodePlace와 달리 필드 마스크가 필요합니다. 해결 방법: 모든SearchDestinations요청에X-Goog-FieldMask헤더 또는$fields매개변수를 설정합니다. /maps/documentation/geocoding/choose-fields를 참고하세요. - 문제: v4
GeocodeAddress에는 하드 구성요소 필터(v3components=country:US)가 없습니다. 구조화된address.*매개변수는 하나의 주소로 결합되며 결과를 필터링하지 않습니다.regionCode에도 v4에 기본값이 없습니다(v3 기본값은us). 해결 방법: 클라이언트 측에서results를 필터링합니다. 대문자regionCode를postalAddress.regionCode에 일치시키고, 대문자 2자리 관리 지역을postalAddress.administrativeArea및administrative_area_level_naddressComponents(shortText)에 일치시킵니다. 입력과postalAddress.postalCode를 모두 정규화합니다(공백/하이픈을 제거하고 지역 규칙을 적용). /maps/documentation/geocoding/geocoding-v4-migrate를 참고하세요. - 문제: 브라우저 JavaScript에서 Geocoding API v4를 직접 호출하면 API 키가 노출됩니다.
Referer헤더를 위조하여 HTTP 리퍼러 제한을 우회할 수 있습니다. 해결 방법: 보호된 키를 사용하여 자체 백엔드에서 v4를 호출하거나 클라이언트 측 요구사항에 Maps JavaScript API Geocoding Service(v3 백엔드)를 사용합니다. /maps/documentation/geocoding/geocoding-v4-migrate를 참고하세요. - 문제:
SearchDestinations는 v3 및 다른 v4 메서드와 달리 정확한 기본 주소가 없는 결과를 반환할 수 있습니다. 수정: 정확한 기본 주소가 있는 결과만 필요한 경우placeFilter.addressability를PRIMARY로 설정합니다. /maps/documentation/geocoding/geocoding-v4-migrate를 참고하세요. - 문제: Geocoding API v3용으로 작성된 코드가 v4 REST 응답에서 작동하지 않습니다. v4는 lowerCamelCase 필드 이름(
address_components가 아닌addressComponents)을 사용하고,status및error_message를 삭제하며,results배열 대신GeocodePlace에서 단일 루트 객체를 반환합니다. 수정: v4 REST 호출에서 HTTP 상태 코드와 오류 본문을 확인하고, lowerCamelCase 필드(addressComponents,postalAddress)를 읽고, gRPC 응답은 여전히 스네이크 표기법을 사용한다는 점에 유의하세요. /maps/documentation/geocoding/geocoding-v4-migrate를 참고하세요.
Geocoding API: 기존 및 지원 중단된 기능
- Geocoding API v3 세부 지역 데이터(
extra_computations:BUILDING_AND_ENTRANCES,NAVIGATION_POINTS,GROUNDS, 응답 필드buildings.entrances,navigation_points,buildings.building_outlines,grounds): 2025년 8월 13일부터 지원 중단됩니다. 대체: Geocoding API v4SearchDestinations메서드(POST /v4/geocode/destinations). 이전 가이드를 참고하세요.
Geocoding API로 할 수 있는 작업
각 작업에 대해 아래에 링크된 가이드를 참조하거나 기능 탐색기에서 제품 간에 비교하세요.
- 주소의 위도/경도 좌표를 반환합니다(지오코딩).
- 위도/경도 좌표 집합의 주소를 반환합니다(역 지오코딩).
- 특정 표시 영역 내의 결과를 반환하도록 지오코딩 요청을 제한합니다. 참고: Geocoding API v4에서 locationBias는 결과를 엄격하게 제한하는 대신 지정된 표시 영역에 편중된 결과를 반환합니다.
- 특정 지역, 국가 또는 우편번호 내의 결과만 반환하도록 지오코딩 또는 역 지오코딩 요청을 제한합니다. 참고: Geocoding API v4에서 regionCode는 결과를 엄격하게 제한하는 대신 지정된 CLDR 지역으로 편향시킵니다. 국가 또는 우편번호별 기존 v3 구성요소 필터링은 https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering을 참고하세요.
- 지정된 주소 유형의 결과만 반환하도록 역 지오코딩 요청을 제한합니다. 참고: Geocoding API v4에서 유형 매개변수는 기본 검색을 제한하는 대신 검색 후 반환된 역 지오코딩 결과를 주소 유형별로 필터링합니다.
- 주소의 명소 또는 지역과의 근접성에 대한 정보를 반환합니다.
- 위도/경도 좌표 집합의 명소 또는 지역과의 근접성에 관한 정보를 반환합니다.
- Google 장소 식별자의 랜드마크 또는 지역과의 근접성에 관한 정보를 반환합니다.
- Google 장소 식별자의 주소를 반환합니다.
- 주소의 건물 윤곽선 위도/경도 좌표를 반환합니다.
- 위도/경도 좌표 집합에 대한 건물 윤곽선의 위도/경도 좌표를 반환합니다.
- Google 장소 식별자의 건물 윤곽선 위도/경도 좌표를 반환합니다.
- 주소에 해당하는 건물 입구의 위도/경도 좌표를 반환합니다.
- 위도/경도 좌표 집합에 대한 건물 입구의 위도/경도 좌표를 반환합니다.
- Google 장소 식별자의 건물 입구 위도/경도 좌표를 반환합니다.