Places API(신규)는 시설, 지리적 위치, 관심 장소에 관한 JSON 위치 데이터를 반환하는 웹 서비스입니다. 텍스트 검색(신규), 주변 지역 검색(신규), 자동 완성(신규), 장소 세부정보(신규), 장소 사진(신규)을 지원합니다.
Places API(신규): 주요 사실
- 제품: Places API(신규)
- 다른 이름: Places API
- 카테고리: 장소
- 플랫폼: 웹 서비스(REST)
- 실행 위치: 서버(백엔드 코드)
- 출시 단계: GA
- 수명 주기: 활성
- 개요: Places API(신규) 개요
- 신청 가능 지역: 전 세계 EEA 청구서 수신 주소가 있는 프로젝트는 Google Maps Platform EEA 서비스 약관(2025년 7월 8일부터 시행)을 사용하며, 위도, 경도, 장소 ID 이외의 Places API 콘텐츠는 장소 UI 키트를 통해서만 지도와 함께 사용할 수 있습니다. AI 기반 장소, 리뷰, 지역 요약은 지원되는 언어 및 지역에서만 사용할 수 있습니다.
Places API(신규): 사용 시기
다음과 같은 경우 Places API(신규)를 사용하세요.
- 텍스트 쿼리(텍스트 검색(신규))를 사용하거나 위치 주변(주변 지역 검색(신규))에서 서버의 장소를 검색해야 합니다.
- Autocomplete(신규)를 통해 백엔드에서 미리 입력 장소 또는 검색어 예상 검색어가 필요합니다.
- 장소 ID가 있으며 주소, 전화번호, 평점, 리뷰, 사진과 같은 세부정보가 필요합니다.
- 장소에 대한 AI 기반 장소, 리뷰 또는 지역 요약이 필요합니다.
다음과 같은 경우에는 Places API(신규)를 사용하지 마세요.
- 네이티브 Android 앱을 빌드하는 경우 Android용 Places SDK를 대신 사용하세요.
- 네이티브 iOS 앱을 빌드하고 있습니다. 대신 iOS용 Places SDK를 사용하세요.
- 브라우저 웹 앱을 빌드하고 있으며 JavaScript로 장소 라이브러리를 로드하려고 합니다. 대신 Maps JavaScript API를 사용하세요.
Places API(신규): 설정
- 사용 설정할 서비스:
places.googleapis.com - 인증: API 키, OAuth 2.0
- 시작하기: Places API(신규) 설정
- 참조: Places API(신규) 참조
- 가격 책정: Places API(신규) 사용량 및 결제
- 정책: Places API(신규) 정책
- 출시 노트: Places API(신규) 출시 노트
공식 Places API(신규) 패키지:
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
Places API(신규): 관련 상품
- 대체: Places API(기존)
- 함께 자주 사용되는 API: Geocoding API, Routes API, Address Validation API
Places API(신규): 일반적인 실수
- 문제: 장소 세부정보(New), 주변 지역 검색(New), 텍스트 검색(New)에는 반환되는 필드의 기본 목록이 없습니다. 필드 마스크가 없는 요청은 오류를 반환합니다. 해결 방법:
fields또는$fields매개변수 또는X-Goog-FieldMask헤더를 사용하여 응답 필드 마스크를 전달합니다. /maps/documentation/places/web-service/choose-fields를 참고하세요. - 문제: 세션이 종료된 후 Autocomplete(New) 세션 토큰이 생략되거나 재사용되면 각 요청에 대해 SKU: Autocomplete Requests로 별도로 요금이 청구됩니다. 해결 방법: 각 세션에 대해 새 세션 토큰(UUID v4 권장)을 생성하고 장소 세부정보(New) 또는 Address Validation 요청으로 세션을 종료합니다. /maps/documentation/places/web-service/place-session-tokens를 참고하세요.
- 문제: 기존 API가 사용 설정되지 않은 프로젝트에서 Places API(기존) 또는 Maps JavaScript API
PlacesService를 호출하는 기존 코드 또는 AI 생성 코드가LegacyApiNotActivatedMapError오류로 인해 실패합니다. 해결 방법: 호출을 Places API(신규)로 이전하고 필수 필드 마스크를 포함합니다. /maps/legacy#LegacyApiNotActivatedMapError를 참고하세요. - 문제: 저장된 장소 ID가 오래되어 장소 세부정보(신규)에서
NOT_FOUND(HTTP 404)를 반환하고, 잘못된 형식의 ID 또는 잘린 ID는 HTTP 400INVALID_ARGUMENT을 반환할 수 있습니다. 해결 방법:id필드만 요청하는 장소 세부정보(신규) 요청을 사용하여 12개월이 지난 저장된 장소 ID를 새로고침합니다(무료). /maps/documentation/places/web-service/place-id#refresh-id를 참고하세요.
Places API(신규)로 할 수 있는 작업
각 작업에 대해 아래에 링크된 가이드를 참조하거나 기능 탐색기에서 제품 간에 비교하세요.
Places API(신규): 생성형 AI
- 지정된 Google 장소 식별자에 대한 사용자 리뷰의 AI 기반 요약을 반환합니다.
- 전기자동차 충전소의 지정된 Google 장소 식별자를 둘러싼 지역 및 편의 시설에 대한 AI 기반 장소 요약을 반환합니다.
Places API(신규): 장소
- 쿼리 문자열을 기반으로 장소 목록과 장소 세부정보를 반환합니다.
- 특정 위치 주변의 장소 목록과 장소 세부정보를 반환합니다.
- 쿼리 문자열을 기반으로 장소에 대한 자동 완성 결과를 반환합니다.
- 특정 장소에 대한 세부정보를 반환합니다.
- 특정 장소의 사진을 반환합니다. 참고: 각 사진의 작성자 저작자 표시(작성자 이름, 프로필 URI에 연결됨)를 사진과 함께 표시합니다. 각 플랫폼의 장소 정책(예: /maps/documentation/javascript/policies#photo-attributions 및 /maps/documentation/places/web-service/policies#photos-and-review)에서 이를 요구합니다.
- 장소 사진 크기 조절
- 특정 장소의 평점과 리뷰를 반환합니다. 참고: Places API(신규) 웹 서비스에서 장소 세부정보는 X-Goog-FieldMask(예: rating,userRatingCount,reviews)를 사용하여 https://places.googleapis.com/v1/places/{placeId}에 대한 HTTP GET 요청입니다. 텍스트 검색, 주변 지역 검색, 자동 완성은 POST를 사용합니다. Android에서는 Place.Field.RATING, USER_RATING_COUNT, REVIEWS를 PlacesClient.fetchPlace()에 전달합니다. iOS에서는 GMSFetchPlaceRequest에 GMSPlacePropertyRating, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyReviews를 전달합니다.
- 장소 정보 응답에 포함된 데이터 필드를 지정합니다.
- 장소 정보 응답에 포함할 장소 유형을 지정합니다.
- Google 지도에서 장소의 장소 세부정보 페이지를 여는 URI를 반환합니다.
- Google 지도에서 장소의 경로 페이지를 여는 URI를 반환합니다.
- Google 지도에서 장소의 리뷰 작성 페이지를 여는 URI를 반환합니다.
- Google 지도에서 장소의 리뷰 읽기 페이지를 여는 URI를 반환합니다.
- Google 지도에서 장소의 사진 페이지를 여는 URI를 반환합니다.
- 특정 장소에 대한 AI 기반 개요 요약을 반환합니다.
- 특정 장소 주변의 장소를 설명하는 AI 기반 지역 요약을 반환합니다.
- 사전 정의된 경로를 따라 위치한 장소에 대한 정보를 쿼리 문자열을 기반으로 반환합니다.
- 위도/경도 좌표 집합에서 텍스트 검색 장소까지의 거리, 이동 시간, 경로 URI를 반환합니다.
- 위도/경도 좌표 세트에서 주변 장소까지의 거리, 이동 시간, 경로 URI를 반환합니다.
- 사전 정의된 경로의 출발지와 쿼리 문자열을 기반으로 반환된 각 장소(경로를 따라 위치함) 간의 거리, 이동 시간, 경로 URI를 반환합니다.
- 쿼리 문자열을 기반으로 반환된 각 장소(사전 정의된 경로를 따라 위치함)와 경로 목적지 간의 거리, 이동 시간, 경로 URI를 반환합니다.