Geocoding v3에서 v4로 이전

유럽 경제 지역 (EEA) 개발자

Geocoding API v4에는 API v3의 기능을 대체하는 여러 새로운 엔드포인트가 도입되었습니다. 이 가이드에서는 새 v4 엔드포인트를 사용하도록 앱을 이전하는 방법을 보여줍니다.

새 v4 엔드포인트와 함께 기존 API 키를 사용할 수 있습니다. 하지만 API v3의 할당량 상향을 요청한 경우 새 v4 API의 상향을 요청해야 합니다. JavaScript 사용자를 위한 이전 경로가 없습니다.

v3 순방향 지오코딩에서 이전

지오코딩을 사용하여 주소를 지오코딩하는 경우 GET 요청을 허용하는 v4 주소 지오코드 엔드포인트로 마이그레이션해야 합니다.

v4 API는 여러 매개변수의 이름, 구조, 지원을 변경합니다. 필드 마스크를 사용하여 응답에서 반환할 필드를 지정하는 것이 좋습니다.

요청 매개변수 변경

v3 매개변수 v4 매개변수 참고
address, components address 구조화되지 않은 주소 (v3 address)가 이제 URL 경로에 전달됩니다. 이제 구성요소 필터 (v3 components)가 address.* 쿼리 매개변수로 전달됩니다.
bounds locationBias.rectangle 이름이 변경되었으며 구조가 객체로 변경되었습니다.
language languageCode 이름이 변경되었습니다.
region regionCode 이름이 변경되었습니다.
extra_computations 삭제됨

응답 필드 변경사항

v3 필드 v4 필드 참고
status, error_message 삭제됨 v4는 HTTP 상태 코드와 오류 본문을 사용합니다.
results.address_components.long_name/results.address_components.short_name results.addressComponents.longText/results.addressComponents.shortText 이름이 변경되었습니다.
results.geometry.location_type results.granularity 이름이 변경되었습니다.
results.geometry.location results.location 필드 이름: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport 필드 이름: northeast/southwest -> high/low
results.postcode_localities results.postalCodeLocalities 이름이 변경되었습니다. 이제 하나 이상의 지역에 대해 반환됩니다 (v3 필요 > 1).
results.partial_match 삭제됨
신규 results.addressComponents.languageCode 특정 주소 구성요소의 언어입니다.
신규 results.bounds high/low을 사용한 명시적 경계
신규 results.place 장소의 리소스 이름입니다.
신규 results.postalAddress 구조화된 PostalAddress 객체입니다.

v3 역 지오코딩에서 이전

역 지오코딩을 사용하여 좌표를 주소로 변환하는 경우 GET 요청을 허용하는 v4 위치 역 지오코드 엔드포인트로 이전해야 합니다.

v4 API는 여러 매개변수의 이름, 구조, 지원을 변경합니다. 필드 마스크를 사용하여 응답에서 반환할 필드를 지정하는 것이 좋습니다.

요청 매개변수 변경

v3 매개변수 v4 매개변수 참고
language languageCode 이름이 변경되었습니다.
region regionCode 이름이 변경되었습니다.
result_type types 이름이 변경되었으며 반복되는 쿼리 매개변수를 사용합니다.
location_type granularity 이름이 변경되었으며 반복되는 쿼리 매개변수를 사용합니다.
extra_computations 삭제됨

응답 필드 변경사항

v3 필드 v4 필드 참고
status, error_message 삭제됨 v4는 HTTP 상태 코드와 오류 본문을 사용합니다.
results.address_components.long_name/results.address_components.short_name results.addressComponents.longText/results.addressComponents.shortText 이름이 변경되었습니다.
results.geometry.location_type results.granularity 이름이 변경되었습니다.
results.geometry.location results.location 필드 이름: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport 필드 이름: northeast/southwest -> high/low
신규 results.addressComponents.languageCode 특정 주소 구성요소의 언어입니다.
신규 results.bounds high/low을 사용한 명시적 경계
신규 results.place 장소의 리소스 이름입니다.
신규 results.postalAddress 구조화된 PostalAddress 객체입니다.

v3 장소 지오코딩에서 이전

place_id를 사용하여 Geocoding v3으로 특정 장소 ID의 주소를 가져오는 경우 GET 요청을 허용하는 v4 장소 지오코딩 엔드포인트로 이전해야 합니다.

v4 API는 여러 매개변수의 이름, 구조, 지원을 변경합니다. 필드 마스크를 사용하여 응답에서 반환할 필드를 지정하는 것이 좋습니다.

요청 매개변수 변경

v3 매개변수 v4 매개변수 참고
place_id 요청 프로토의 place 필드 이제 장소 ID가 경로 매개변수 places/{place}로 제공됩니다(예: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw). 이는 기본 요청의 장소 필드에 매핑됩니다.
language languageCode 이름이 변경되었습니다.
region regionCode 이름이 변경되었습니다.

응답 필드 변경사항

v3 필드 v4 필드 참고
status, error_message 삭제됨 v4는 HTTP 상태 코드와 오류 본문을 사용합니다.
results (루트) v4는 results 배열이 아닌 단일 결과 객체를 반환합니다.
results.address_components.long_name/results.address_components.short_name addressComponents.longText/addressComponents.shortText 이름이 변경되었습니다.
results.geometry.location_type granularity 이름이 변경되었습니다.
results.geometry.location location 필드 이름: lat/lng -> latitude/longitude
results.geometry.viewport viewport 필드 이름: northeast/southwest -> high/low
results.postcode_localities postalCodeLocalities 이름이 변경되었습니다. 이제 하나 이상의 지역에 대해 반환됩니다 (v3 필요 > 1).
신규 addressComponents.languageCode 특정 주소 구성요소의 언어입니다.
신규 bounds high/low을 사용한 명시적 경계
신규 place 장소의 리소스 이름입니다.
신규 postalAddress 구조화된 PostalAddress 객체입니다.

Geocoding Hyperlocal Data에서 Destinations로 이전

Geocoding API v3의 다음 기능은 Geocoding API v4의 SearchDestinations 엔드포인트로 대체됩니다.

  • 진입수
  • 탐색 지점
  • 개요 작성
  • 입장권

위 기능에 Geocoding API v3를 사용하고 있었다면 이 문서를 참고하여 대신 SearchDestinations 엔드포인트를 사용하여 이러한 기능을 구현하세요. 이 문서에서는 SearchDestinations API 응답에서 이러한 기능을 찾을 수 있는 위치와 Geocoding API v3와 Geocoding API v4의 SearchDestinations 엔드포인트 간에 API 응답에 이러한 기능이 표시되는 방식의 차이점을 설명합니다.

진입수

destination와 연결된 입구를 가져오려면 destination.entrances 필드를 사용합니다.

entrance의 형식은 Geocoding API v3의 진입 형식과 약간 다릅니다. destination.entrances의 각 입구에는 다음 필드가 있습니다.

  • displayName - 출입구의 사람이 읽을 수 있는 이름을 갖는 새로운 선택적 필드입니다(예: 'Gate B').
  • location - LatLng 유형의 위치입니다. Geocoding API v3에서 사용되는 형식과 다릅니다.
  • tags - Geocoding API v3의 진입로 tags 필드와 동일합니다.
  • place - Geocoding API v3의 진입점 buildingPlaceId 필드와 유사합니다. 하지만 이 필드의 장소 ID는 건물뿐 아니라 모든 유형의 장소에 해당할 수 있습니다.

destination와 연결된 탐색 포인트를 가져오려면 destination.navigationPoints 필드를 사용합니다.

navigationPoint의 형식은 Geocoding API v3의 탐색 지점 형식과 약간 다릅니다. destination.navigationPoints의 각 탐색 지점에는 다음 필드가 있습니다.

  • displayName - 탐색 지점의 사람이 읽을 수 있는 이름(예: '5th Ave')이 포함된 새로운 선택적 필드입니다.
  • location - LatLng 유형의 위치입니다. Geocoding API v3에서 사용되는 형식과 다릅니다.
  • travelModes - Geocoding API v3의 탐색 지점 restrictedTravelModes 필드와 유사합니다. 가능한 열거형 값은 동일하며, 이제 이 필드는 제한된 이동 모드가 아닌 탐색 지점에 허용되는 이동 모드를 나타낸다는 점만 다릅니다.
  • usage - 탐색 지점에서 지원하는 사용 사례를 포함하는 새로운 필드입니다. 대부분의 탐색 지점에는 UNKNOWN 사용이 있지만 탐색 지점의 사용이 어떤 방식으로든 제한된다는 의미는 아닙니다.

개요 작성

destination와 연결된 건물 윤곽선을 가져오려면 건물을 나타내는 destination의 placeView 객체의 displayPolygon 필드를 사용해야 합니다. 각 placeView의 경우 placeView.structureType 필드를 사용하여 건물인지 확인할 수 있습니다. 구조 유형이 BUILDING인 경우 placeView.displayPolygon 필드에서 개요를 가져올 수 있습니다. placeView에는 Geocoding API v3에 없던 건물의 추가 필드도 있습니다.

destination에는 다음 필드에 건물을 나타내는 placeView 객체가 있을 수 있습니다.

  • destination.primary - 대상의 기본 위치입니다.
  • destination.containingPlaces - 기본 장소를 '포함'하는 더 큰 장소를 보유할 수 있는 반복되는 필드입니다. 예를 들어 기본 장소가 subpremise인 경우 containingPlaces에는 일반적으로 건물을 나타내는 placeView가 포함됩니다.
  • destination.subDestinations - 기본 장소의 하위 목적지를 보유할 수 있는 반복 필드입니다. 예를 들어 건물의 개별 아파트 단위입니다. 이 필드에는 일반적으로 건물을 나타내는 placeView가 없습니다.

placeView.displayPolygon의 형식은 RFC 7946 형식을 사용하는 GeoJSON 형식인 Geocoding API v3의 건물 윤곽선 형식과 일치합니다.

입장권

윤곽선을 빌드하는 것과 마찬가지로 destination와 연결된 근거를 가져오려면 근거를 나타내는 destination의 placeView 객체에 있는 displayPolygon 필드를 사용해야 합니다. 각 placeView에 대해 placeView.structureType 필드를 사용하여 근거인지 확인할 수 있습니다. 구조 유형이 GROUNDS인 경우 placeView.displayPolygon 필드에서 개요를 가져올 수 있습니다. placeView에는 Geocoding API v3에 없었던 근거를 위한 추가 필드도 있습니다.

destination에는 다음 필드에서 근거를 나타내는 placeView 객체가 있을 수 있습니다.

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

placeView.displayPolygon의 형식은 RFC 7946 형식을 사용하는 GeoJSON 형식인 Geocoding API v3의 지형 개요 형식과 일치합니다.

필드 마스크를 사용하여 이러한 기능 요청

SearchDestinations 엔드포인트에는 반환할 필드 선택에 설명된 대로 필드 마스크가 필요합니다. 모든 필드를 반환하도록 필드 마스크를 *로 설정하거나 수신하려는 특정 필드로 설정할 수 있습니다. 예를 들어 다음 API 요청은 대상의 출입구, 탐색 지점, 건물 윤곽선, 지면을 가져오는 데 필요한 모든 필드를 수신하도록 필드 마스크를 설정합니다.

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations