Geocoding API 빠른 참조

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 API: 일반적인 실수

  • 문제: 필드 마스크가 없는 SearchDestinations 요청은 오류와 함께 실패합니다. GeocodeAddress, GeocodeLocation, GeocodePlace와 달리 필드 마스크가 필요합니다. 해결 방법: 모든 SearchDestinations 요청에 X-Goog-FieldMask 헤더 또는 $fields 매개변수를 설정합니다. /maps/documentation/geocoding/choose-fields를 참고하세요.
  • 문제: v4 GeocodeAddress에는 하드 구성요소 필터(v3 components=country:US)가 없습니다. 구조화된 address.* 매개변수는 하나의 주소로 결합되며 결과를 필터링하지 않습니다. regionCode에도 v4에 기본값이 없습니다(v3 기본값은 us). 해결 방법: 클라이언트 측에서 results를 필터링합니다. 대문자 regionCode를 postalAddress.regionCode에 일치시키고, 대문자 2자리 관리 지역을 postalAddress.administrativeArea 및 administrative_area_level_n addressComponents(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 v4 SearchDestinations 메서드(POST /v4/geocode/destinations). 이전 가이드를 참고하세요.

Geocoding API로 할 수 있는 작업

각 작업에 대해 아래에 링크된 가이드를 참조하거나 기능 탐색기에서 제품 간에 비교하세요.