Android용 Places SDK 빠른 참조

Android용 Places SDK를 사용하면 Android 앱에서 Place Autocomplete, 장소 세부정보, 주변 지역 검색, 텍스트 검색, 장소 사진을 통해 Google의 장소 및 비즈니스 정보 데이터베이스에 액세스할 수 있습니다. Android용 Places SDK(신규)는 현재 버전이며 Places API(신규)에 종속됩니다.

Android용 Places SDK: 주요 사실

  • 제품: Android용 Places SDK
  • 다른 이름: Android용 Places SDK(신규)
  • 카테고리: 장소
  • 플랫폼: Android
  • 실행 위치: 클라이언트(앱 또는 브라우저 코드)
  • 출시 단계: GA
  • 수명 주기: 활성
  • 개요: Android용 Places SDK 개요

Android용 Places SDK: 사용 시기

다음과 같은 경우 Android용 Places SDK를 사용하세요.

  • 네이티브 Android 앱 내에 장소 세부정보, 사진, 주변 지역 검색 또는 텍스트 검색 결과가 필요합니다.
  • 사용자가 Android 앱에 입력할 때 장소 예상 검색어를 반환하는 사전 제작된 자동 완성 위젯 또는 장소 UI 키트 구성요소가 필요합니다.
  • 사용자 기기 근처의 비즈니스 및 관심 장소를 기반으로 위치 인식 Android 기능을 빌드해야 합니다.

다음과 같은 경우에는 Android용 Places SDK를 사용하지 마세요.

  • Android 앱이 아닌 서버 또는 백엔드에서 HTTP를 통해 Places를 호출해야 합니다. 대신 Places API(신규)를 사용하세요.
  • 네이티브 iOS 앱을 빌드하고 있습니다. 대신 iOS용 Places SDK를 사용하세요.
  • 브라우저에서 웹페이지를 빌드하고 있습니다. 대신 Maps JavaScript API를 사용하세요.

Android용 Places SDK: 설정

공식 Android용 Places SDK 패키지:

  • maven: com.google.android.libraries.places:places

Android용 Places SDK: 일반적인 실수

  • 문제: 필드 목록(필드 마스크)이 없거나 비어 있는 주변 지역 검색 요청은 오류를 반환합니다. 해결 방법: SearchNearbyRequest 필드 목록에 Place.Field를 하나 이상 전달합니다. /maps/documentation/places/android-sdk/nearby-search를 참고하세요.
  • 문제: API 키에 Places API(신규)가 없거나 SDK 5.x 이하에서 앱이 Places.initialize()를 호출하는 경우 장소 세부정보(신규), 주변 지역 검색(신규), 자동 완성(신규)이 실패합니다. 버전 6.0.2에서 Places.initialize()가 삭제되었으므로 업그레이드 후 이를 호출하는 코드가 컴파일되지 않습니다. 해결 방법: Places API(신규)를 사용 설정하고 API 키의 허용된 API에 추가한 후 Places.initializeWithNewPlacesApiEnabled()로 초기화합니다. /maps/documentation/places/android-sdk/legacy/migrate-overview를 참고하세요.
  • 문제: 필드 목록에서 PHOTO_METADATAS를 생략하면 fetchPlace()에서 반환된 Place에 PhotoMetadata가 없습니다(따라서 확인할 항목이 없음). 해결 방법: 필드 목록에 Place.Field.PHOTO_METADATAS를 포함합니다. fetchResolvedPhotoUri()는 지원 중단되었으므로 장소 UI 키트 장소 세부정보 구성요소를 사용하여 사진을 표시하세요. /maps/documentation/places/android-sdk/place-photos를 참고하세요.
  • 문제: 반환된 서드 파티 및 작성자 저작자 표시 없이 장소 세부정보, 사진 또는 리뷰를 표시하는 앱은 정책을 위반합니다. 해결 방법: Place, PhotoMetadata, Review 객체와 함께 반환된 저작자 표시를 표시합니다. /maps/documentation/places/android-sdk/policies를 참고하세요.

Android용 Places SDK: 기존 및 지원 중단된 기능

  • Android용 Places SDK(기존) / Places API(기존) 기능(자동 완성, 현재 장소, 장소 세부정보, 장소 사진 기존): 2025년 3월 1일부터 기존. 대체: Places API(신규)에서 지원하고 Places.initializeWithNewPlacesApiEnabled()로 초기화되는 Android용 Places SDK(신규) 기능 증상: 2026년 10월부터 새 클라우드 프로젝트에서 Places API(기존)를 사용 설정할 수 없습니다(기존 프로젝트는 계속 지원됨). SDK 6.0.2에서는 5.x 이하 버전에만 존재하는 기존 메서드가 삭제되었습니다. 이전 가이드를 참고하세요.
  • Places.initialize(): 2026년 9월 30일부터 사용 중단되었습니다. 교체: Places.initializeWithNewPlacesApiEnabled(). 증상: 6.0.2에서 SDK에서 메서드가 삭제되었습니다. 이 메서드를 호출하는 코드가 더 이상 컴파일되지 않습니다. 이전 가이드를 참고하세요.
  • PlacesClient.findCurrentPlace() 및 awaitFindCurrentPlace()(현재 장소, 기존): 2026년 9월 30일부터 사용 중단되었습니다. 대체: PlacesClient.searchNearby()(주변 지역 검색(New)) 증상: 6.0.2에서 메서드와 FindCurrentPlaceRequest/FindCurrentPlaceResponse 클래스가 삭제되었습니다. 이전 가이드를 참고하세요.
  • PlacesClient.fetchPhoto() 및 awaitFetchPhoto(): 2026년 9월 30일부터 사용 중단됩니다. 대체: 장소 UI 키트 장소 세부정보 구성요소(PlacesClient.fetchResolvedPhotoUri()는 지원 중단됨) 증상: 6.0.2에서 메서드와 FetchPhotoRequest/FetchPhotoResponse 클래스가 삭제되었습니다. 이전 가이드를 참고하세요.
  • Places API(기존) 자동 완성 위젯(Autocomplete, AutocompleteSupportFragment, AutocompleteActivityMode): 2026년 9월 30일부터 사용 중단됩니다. 대체: Place Autocomplete(신규) 위젯(PlaceAutocomplete) 또는 PlacesClient.findAutocompletePredictions(). 증상: 6.0.2에서 SDK에서 클래스가 삭제되었습니다. 이전 가이드를 참고하세요.
  • 장소 호환성 라이브러리(com.google.android.libraries.places:places-compat): 2022년 3월 31일부터 지원 중단되었습니다. 대체: Android용 Places SDK(com.google.android.libraries.places:places). 증상: v2.6.0에서 중단됨, 새로운 기능이나 버그 수정 없음
  • AutocompleteFragment 클래스: 2025년 9월 25일부터 사용 중단되었습니다. 대체: Place Autocomplete(New) 위젯(PlaceAutocomplete). 증상: 5.0.0에서 SDK에서 클래스가 삭제되었습니다(AutocompleteSupportFragment도 6.0.2에서 삭제됨).

Android용 Places SDK로 할 수 있는 작업

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

Android용 Places SDK: 생성형 AI

Android용 Places SDK: 장소

Android용 Places SDK: 장소 UI 키트

  • 장소 데이터 UI 요소에 CSS 스타일을 적용합니다. 참고: CSS 맞춤 속성은 Maps JavaScript API 장소 UI 키트 요소에 적용됩니다. Android용 Places SDK 및 iOS용 Places SDK는 테마 및 스타일 속성을 사용하여 프로그래매틱 방식으로 장소 UI 키트 뷰의 스타일을 지정합니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • UI 요소 맞춤설정 도구를 사용하여 장소 데이터 UI 요소 스타일 지정 및 구성을 맞춤설정합니다. 참고: EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)에서 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 특정 장소에 관한 정보를 표시하는 UI 요소를 웹페이지 또는 모바일 앱에 추가합니다. 참고: EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 쿼리 문자열을 기반으로 장소 목록을 표시하는 UI 요소를 웹페이지에 추가합니다. 참고: 웹페이지(Maps JavaScript API)와 모바일 앱(Android용 Places SDK 및 iOS용 Places SDK)에서 모두 지원됩니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 특정 위치 근처의 장소 목록을 표시하는 UI 요소를 웹페이지에 추가합니다. 참고: 웹페이지(Maps JavaScript API)와 모바일 앱(Android용 Places SDK 및 iOS용 Places SDK)에서 모두 지원됩니다. EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)의 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq
  • 쿼리 문자열을 기반으로 Google 장소 식별자를 반환하는 기본 자동 완성 UI 요소를 웹페이지 또는 앱에 추가합니다. 참고: EEA 규정 준수 요구사항: 유럽 경제 지역(EEA)에서 지도에 장소 데이터를 표시하려면 백엔드 서버에서 Places API 웹 서비스를 호출하지 마세요. 타겟 플랫폼(웹의 경우 Maps JavaScript API, Android의 경우 Android용 Places SDK, iOS의 경우 iOS용 Places SDK)에서 클라이언트 측 장소 UI 키트 구성요소를 사용합니다. 전체 요구사항 및 FAQ: https://developers.google.com/maps/comms/eea/faq