Places API(신규) 빠른 참조

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 API(신규) 패키지:

  • npm: @googlemaps/places
  • pypi: google-maps-places
  • go: cloud.google.com/go/maps

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 400 INVALID_ARGUMENT을 반환할 수 있습니다. 해결 방법: id 필드만 요청하는 장소 세부정보(신규) 요청을 사용하여 12개월이 지난 저장된 장소 ID를 새로고침합니다(무료). /maps/documentation/places/web-service/place-id#refresh-id를 참고하세요.

Places API(신규)로 할 수 있는 작업

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

Places API(신규): 생성형 AI

Places API(신규): 장소