Places SDK cho Android cho phép các ứng dụng Android truy cập vào cơ sở dữ liệu của Google về thông tin địa điểm và doanh nghiệp thông qua các tính năng Place Autocomplete, Place Details, Nearby Search, Tìm kiếm văn bản và Place Photos. Places SDK cho Android (Mới) là phiên bản hiện tại và phụ thuộc vào Places API (Mới).
SDK Địa điểm dành cho Android: thông tin chính
- Sản phẩm: SDK Địa điểm dành cho Android
- Còn gọi là: Places SDK cho Android (Mới)
- Danh mục: Địa điểm
- Nền tảng: Android
- Chạy trên: Ứng dụng khách (mã ứng dụng hoặc trình duyệt)
- Giai đoạn ra mắt: GA
- Vòng đời: Đang hoạt động
- Tổng quan: Tổng quan về SDK Địa điểm cho Android
SDK Địa điểm cho Android: trường hợp sử dụng
Sử dụng SDK Địa điểm cho Android khi:
- Bạn cần có thông tin chi tiết về địa điểm, ảnh, kết quả Tìm kiếm lân cận hoặc Tìm kiếm văn bản trong một ứng dụng Android gốc.
- Bạn cần có một tiện ích tự động hoàn thành có sẵn hoặc các thành phần của Places UI Kit để trả về cụm từ gợi ý về địa điểm khi người dùng nhập thông tin vào một ứng dụng Android.
- Bạn cần xây dựng các tính năng Android nhận biết vị trí dựa trên các doanh nghiệp và địa điểm yêu thích gần thiết bị của người dùng.
Không sử dụng SDK Địa điểm cho Android khi:
- Bạn cần gọi Địa điểm từ một máy chủ hoặc phần phụ trợ qua HTTP thay vì từ một ứng dụng Android. Hãy sử dụng Places API (Mới).
- Bạn đang xây dựng một ứng dụng iOS gốc. Hãy sử dụng SDK Địa điểm cho iOS.
- Bạn đang tạo một trang web trong trình duyệt. Thay vào đó, hãy sử dụng Maps JavaScript API.
SDK Địa điểm dành cho Android: thiết lập
- Dịch vụ cần bật:
places.googleapis.com - Xác thực: Khoá API
- Phân bổ mức sử dụng: Gọi
Places.addInternalUsageAttributionId(String)khi khởi chạy SDK để gửi mã phân bổ mức sử dụng; xoá lệnh gọi hoặc truyền một chuỗi trống để chọn không sử dụng. - Bắt đầu: Thiết lập SDK Địa điểm cho Android
- Tài liệu tham khảo: Tài liệu tham khảo về SDK Địa điểm cho Android
- Giá: Mức sử dụng và thông tin thanh toán của Places SDK for Android
- Chính sách: Chính sách về SDK Địa điểm cho Android
- Ghi chú phát hành: Ghi chú phát hành SDK Địa điểm cho Android
Các gói SDK Địa điểm chính thức dành cho Android:
- maven:
com.google.android.libraries.places:places
Places SDK cho Android: sản phẩm có liên quan
- Thường dùng với: Maps SDK cho Android
SDK Địa điểm cho Android: các lỗi thường gặp
- Vấn đề: Các yêu cầu Nearby Search không có danh sách trường (mặt nạ trường) hoặc có danh sách trường trống sẽ trả về lỗi. Cách khắc phục: Truyền ít nhất một
Place.Fieldtrong danh sách trườngSearchNearbyRequest. Xem /maps/documentation/places/android-sdk/nearby-search. - Vấn đề: Place Details (Mới), Nearby Search (Mới) và Tự động hoàn thành (Mới) không hoạt động khi khoá API thiếu Places API (Mới) hoặc trên SDK 5.x trở xuống khi ứng dụng gọi
Places.initialize(). Phiên bản 6.0.2 đã xoáPlaces.initialize(), vì vậy, mã gọi phiên bản này sẽ không biên dịch sau khi nâng cấp. Cách khắc phục: Bật Places API (Mới), thêm API này vào danh sách API được phép của khoá API và khởi động bằngPlaces.initializeWithNewPlacesApiEnabled(). Xem /maps/documentation/places/android-sdk/legacy/migrate-overview. - Vấn đề:
PlacedofetchPlace()trả về không cóPhotoMetadata(vì vậy, không có gì để phân giải) khi danh sách trường bỏ quaPHOTO_METADATAS. Cách khắc phục: ThêmPlace.Field.PHOTO_METADATASvào danh sách trường. VìfetchResolvedPhotoUri()không còn được dùng nữa, hãy sử dụng thành phần Place Details của Places UI Kit để hiển thị ảnh. Xem /maps/documentation/places/android-sdk/place-photos. - Vấn đề: Những ứng dụng hiển thị Place Details, ảnh hoặc bài đánh giá về địa điểm mà không có thông tin ghi công của bên thứ ba và tác giả được trả về sẽ vi phạm chính sách. Cách khắc phục: Hiển thị thông tin ghi nhận tác giả được trả về cùng với các đối tượng
Place,PhotoMetadatavàReview. Xem /maps/documentation/places/android-sdk/policies.
Places SDK cho Android: các tính năng cũ và không dùng nữa
- Các tính năng của Places SDK cho Android (Phiên bản cũ) / Places API (Phiên bản cũ) (Tự động hoàn thành, Địa điểm hiện tại, Chi tiết địa điểm, Ảnh địa điểm phiên bản cũ): Phiên bản cũ kể từ ngày 1 tháng 3 năm 2025. Thay thế: Các tính năng của Places SDK cho Android (Mới) được hỗ trợ bởi Places API (Mới), được khởi chạy bằng
Places.initializeWithNewPlacesApiEnabled(). Dấu hiệu: Kể từ tháng 10 năm 2026, các dự án trên đám mây mới sẽ không thể bật Places API (Phiên bản cũ) (các dự án hiện tại vẫn được hỗ trợ). SDK 6.0.2 đã xoá các phương thức cũ chỉ có trong phiên bản 5.x trở xuống. Xem hướng dẫn di chuyển. Places.initialize(): Ngừng hoạt động kể từ ngày 30 tháng 9 năm 2026. Thay thế:Places.initializeWithNewPlacesApiEnabled(). Triệu chứng: Phương thức bị xoá khỏi SDK trong phiên bản 6.0.2; mã gọi phương thức này không còn biên dịch được nữa. Xem hướng dẫn di chuyển.PlacesClient.findCurrentPlace()vàawaitFindCurrentPlace()(Địa điểm hiện tại, cũ): Ngừng hoạt động kể từ ngày 30 tháng 9 năm 2026. Thay thế:PlacesClient.searchNearby()(Nearby Search (Mới)). Triệu chứng: Các phương thức và lớpFindCurrentPlaceRequest/FindCurrentPlaceResponseđã bị xoá trong phiên bản 6.0.2. Xem hướng dẫn di chuyển.PlacesClient.fetchPhoto()vàawaitFetchPhoto(): Ngừng hoạt động kể từ ngày 30 tháng 9 năm 2026. Thay thế: Thành phần Place Details của Places UI Kit (PlacesClient.fetchResolvedPhotoUri()không còn được dùng nữa). Triệu chứng: Các phương thức và lớpFetchPhotoRequest/FetchPhotoResponseđã bị xoá trong phiên bản 6.0.2. Xem hướng dẫn di chuyển.- Tiện ích tự động hoàn thành của Places API (Phiên bản cũ) (
Autocomplete,AutocompleteSupportFragment,AutocompleteActivityMode): Ngừng hoạt động kể từ ngày 30 tháng 9 năm 2026. Thay thế: Tiện ích Place Autocomplete (Mới) (PlaceAutocomplete) hoặcPlacesClient.findAutocompletePredictions(). Triệu chứng: Các lớp đã bị xoá khỏi SDK trong phiên bản 6.0.2. Xem hướng dẫn di chuyển. - Thư viện tương thích của Địa điểm (
com.google.android.libraries.places:places-compat): Không dùng nữa kể từ ngày 31 tháng 3 năm 2022. Thay thế: Places SDK cho Android (com.google.android.libraries.places:places). Triệu chứng: Bị đóng băng ở phiên bản 2.6.0; không có tính năng mới hoặc bản sửa lỗi. - Lớp
AutocompleteFragment: Ngừng hoạt động kể từ ngày 25 tháng 9 năm 2025. Thay thế: Tiện ích Place Autocomplete (Mới) (PlaceAutocomplete). Triệu chứng: Lớp đã bị xoá khỏi SDK trong phiên bản 5.0.0 (AutocompleteSupportFragmentcũng bị xoá trong phiên bản 6.0.2).
Những việc bạn có thể làm với Places SDK cho Android
Hãy xem hướng dẫn được liên kết bên dưới cho từng nhiệm vụ hoặc so sánh giữa các sản phẩm trong Trình khám phá chức năng.
Places SDK cho Android: AI tạo sinh
- Trả về bản tóm tắt do AI tạo về các bài đánh giá của người dùng cho một giá trị nhận dạng Địa điểm trên Google được chỉ định.
- Trả về bản tóm tắt địa điểm dựa trên AI về khu vực và các tiện nghi xung quanh một giá trị nhận dạng Địa điểm trên Google được chỉ định cho một trạm sạc xe điện.
Places SDK cho Android: Địa điểm
- Trả về danh sách địa điểm và Place Details dựa trên chuỗi truy vấn.
- Trả về danh sách địa điểm và thông tin chi tiết về địa điểm gần một vị trí cụ thể.
- Trả về kết quả tự động hoàn thành về địa điểm dựa trên một chuỗi truy vấn.
- Trả về thông tin chi tiết về một địa điểm cụ thể.
- Trả về ảnh của một địa điểm cụ thể. Lưu ý: Hiển thị thông tin ghi nhận tác giả của mỗi bức ảnh (tên tác giả, được liên kết với URI hồ sơ của họ) cùng với bức ảnh. Chính sách về Địa điểm cho mỗi nền tảng đều yêu cầu điều này, ví dụ: /maps/documentation/javascript/policies#photo-attributions và /maps/documentation/places/web-service/policies#photos-and-review.
- Đổi kích thước ảnh của địa điểm.
- Trả về điểm xếp hạng và bài đánh giá cho một địa điểm cụ thể. Lưu ý: Trong dịch vụ web Places API (Mới), Chi tiết địa điểm là một yêu cầu HTTP GET đến https://places.googleapis.com/v1/places/{placeId} có X-Goog-FieldMask (ví dụ: rating,userRatingCount,reviews); Tìm kiếm văn bản, Tìm kiếm lân cận và Tự động hoàn thành sử dụng POST. Trên Android, hãy truyền Place.Field.RATING, USER_RATING_COUNT và REVIEWS đến PlacesClient.fetchPlace(). Trên iOS, hãy truyền GMSPlacePropertyRating, GMSPlacePropertyUserRatingsTotal và GMSPlacePropertyReviews trong GMSFetchPlaceRequest.
- Thêm tiện ích tự động hoàn thành vào một trang web hoặc ứng dụng để trả về kết quả về địa điểm dựa trên chuỗi truy vấn.
- Chỉ định các trường dữ liệu có trong phản hồi thông tin về địa điểm.
- Chỉ định các loại địa điểm cần đưa vào phản hồi thông tin về địa điểm.
- Trả về URI để mở trang chi tiết về địa điểm trong Google Maps cho một địa điểm.
- Trả về thông tin về địa điểm mà thiết bị của người dùng đang ở đó. Lưu ý: Các phương thức Địa điểm hiện tại cũ đã bị xoá trong SDK Địa điểm cho Android phiên bản 6.0 trở lên và SDK Địa điểm cho iOS phiên bản 11.0 trở lên; hãy truy xuất toạ độ thiết bị từ các dịch vụ vị trí của nền tảng và gọi Nearby Search.
- Trả về thông tin tóm tắt tổng quan do AI tạo cho một địa điểm cụ thể.
- Trả về thông tin tóm tắt khu vực sử dụng AI, mô tả các địa điểm trong khu vực xung quanh một địa điểm cụ thể.
- Trả về thông tin về các địa điểm dựa trên một chuỗi truy vấn nằm dọc theo một tuyến đường được xác định trước.
- Trả về khoảng cách, thời gian di chuyển và URI chỉ đường đến các địa điểm tìm kiếm bằng văn bản từ một tập hợp toạ độ vĩ độ/kinh độ.
- Trả về khoảng cách, thời gian di chuyển và URI chỉ đường đến các địa điểm lân cận từ một tập hợp toạ độ vĩ độ/kinh độ.
- Trả về khoảng cách, thời gian di chuyển và URI chỉ đường giữa điểm xuất phát của một tuyến đường được xác định trước và từng địa điểm được trả về dựa trên một chuỗi truy vấn, cũng nằm dọc theo tuyến đường đó.
- Trả về khoảng cách, thời gian di chuyển và URI chỉ đường giữa mỗi địa điểm được trả về dựa trên một chuỗi truy vấn, cũng nằm dọc theo một tuyến đường được xác định trước và đích đến của tuyến đường.
Places SDK cho Android: Places UI Kit
- Áp dụng kiểu CSS cho một phần tử trên giao diện người dùng của dữ liệu địa điểm. Lưu ý: Các thuộc tính tuỳ chỉnh CSS áp dụng cho các phần tử của Places UI Kit trong API JavaScript của Maps; Places SDK cho Android và Places SDK cho iOS tạo kiểu cho các thành phần hiển thị của Places UI Kit theo phương thức lập trình bằng cách sử dụng các thuộc tính giao diện và kiểu. YÊU CẦU TUÂN THỦ ĐỐI VỚI KHU VỰC KINH TẾ CHÂU ÂU (EEA): Để hiển thị dữ liệu địa điểm trên bản đồ ở Khu vực kinh tế Châu Âu (EEA), đừng gọi dịch vụ web của Places API từ máy chủ phụ trợ. Sử dụng các thành phần của Places UI Kit phía máy khách trên nền tảng mục tiêu (Maps JavaScript API trên web, Places SDK cho Android trên Android hoặc Places SDK cho iOS trên iOS). Yêu cầu đầy đủ và Câu hỏi thường gặp: https://developers.google.com/maps/comms/eea/faq
- Tuỳ chỉnh định kiểu và cấu hình của phần tử trên giao diện người dùng cho dữ liệu địa điểm bằng công cụ tuỳ chỉnh phần tử trên giao diện người dùng. Lưu ý: YÊU CẦU TUÂN THỦ Ở KHU VỰC KINH TẾ CHÂU ÂU (EEA): Để hiển thị dữ liệu địa điểm trên bản đồ ở Khu vực kinh tế Châu Âu (EEA), đừng gọi dịch vụ web của Places API từ máy chủ phụ trợ. Sử dụng các thành phần của Places UI Kit phía máy khách trên nền tảng mục tiêu (Maps JavaScript API trên web, Places SDK cho Android trên Android hoặc Places SDK cho iOS trên iOS). Yêu cầu đầy đủ và Câu hỏi thường gặp: https://developers.google.com/maps/comms/eea/faq
- Thêm một phần tử trên giao diện người dùng để hiển thị thông tin về một địa điểm cụ thể trên trang web hoặc ứng dụng di động. Lưu ý: YÊU CẦU TUÂN THỦ ĐỐI VỚI KHU VỰC KINH TẾ CHÂU ÂU (EEA): Để hiển thị dữ liệu địa điểm trên bản đồ ở Khu vực kinh tế Châu Âu (EEA), đừng gọi dịch vụ web của Places API từ máy chủ phụ trợ. Sử dụng các thành phần của Places UI Kit phía máy khách trên nền tảng mục tiêu (Maps JavaScript API trên web, Places SDK cho Android trên Android hoặc Places SDK cho iOS trên iOS). Yêu cầu đầy đủ và Câu hỏi thường gặp: https://developers.google.com/maps/comms/eea/faq
- Thêm một phần tử trên giao diện người dùng để hiển thị danh sách địa điểm dựa trên chuỗi truy vấn vào trang web. Lưu ý: Được hỗ trợ trên cả trang web (Maps JavaScript API) và ứng dụng di động (SDK Địa điểm cho Android và SDK Địa điểm cho iOS). YÊU CẦU TUÂN THỦ ĐỐI VỚI KHU VỰC KINH TẾ CHÂU ÂU (EEA): Để hiển thị dữ liệu địa điểm trên bản đồ ở Khu vực kinh tế Châu Âu (EEA), đừng gọi dịch vụ web của Places API từ máy chủ phụ trợ. Sử dụng các thành phần của Places UI Kit phía máy khách trên nền tảng mục tiêu (Maps JavaScript API trên web, Places SDK cho Android trên Android hoặc Places SDK cho iOS trên iOS). Yêu cầu đầy đủ và Câu hỏi thường gặp: https://developers.google.com/maps/comms/eea/faq
- Thêm một phần tử trên giao diện người dùng vào trang web để hiển thị danh sách các địa điểm gần một vị trí cụ thể. Lưu ý: Được hỗ trợ trên cả trang web (Maps JavaScript API) và ứng dụng di động (SDK Địa điểm cho Android và SDK Địa điểm cho iOS). YÊU CẦU TUÂN THỦ ĐỐI VỚI KHU VỰC KINH TẾ CHÂU ÂU (EEA): Để hiển thị dữ liệu địa điểm trên bản đồ ở Khu vực kinh tế Châu Âu (EEA), đừng gọi dịch vụ web của Places API từ máy chủ phụ trợ. Sử dụng các thành phần của Places UI Kit phía máy khách trên nền tảng mục tiêu (Maps JavaScript API trên web, Places SDK cho Android trên Android hoặc Places SDK cho iOS trên iOS). Yêu cầu đầy đủ và Câu hỏi thường gặp: https://developers.google.com/maps/comms/eea/faq
- Thêm một phần tử trên giao diện người dùng tự động hoàn thành cơ bản vào một trang web hoặc ứng dụng trả về giá trị nhận dạng Địa điểm trên Google dựa trên một chuỗi truy vấn. Lưu ý: YÊU CẦU TUÂN THỦ Ở KHU VỰC KINH TẾ CHÂU ÂU (EEA): Để hiển thị dữ liệu địa điểm trên bản đồ ở Khu vực kinh tế Châu Âu (EEA), đừng gọi dịch vụ web của Places API từ máy chủ phụ trợ. Sử dụng các thành phần của Places UI Kit phía máy khách trên nền tảng mục tiêu (Maps JavaScript API trên web, Places SDK cho Android trên Android hoặc Places SDK cho iOS trên iOS). Yêu cầu đầy đủ và Câu hỏi thường gặp: https://developers.google.com/maps/comms/eea/faq