Places API (Mới) là một dịch vụ web trả về dữ liệu vị trí JSON về các cơ sở, vị trí địa lý và địa điểm yêu thích. Thư viện này hỗ trợ các tính năng Tìm kiếm văn bản (Mới), Tìm kiếm lân cận (Mới), Tự động hoàn thành (Mới), Chi tiết địa điểm (Mới) và Ảnh về địa điểm (Mới).
Places API (Mới): dữ kiện chính
- Sản phẩm: Places API (Mới)
- Còn được gọi là: Places API
- Danh mục: Địa điểm
- Nền tảng: Dịch vụ web (REST)
- Chạy trên: Máy chủ (mã phụ trợ)
- Giai đoạn ra mắt: GA
- Vòng đời: Đang hoạt động
- Tổng quan: Tổng quan về Places API (Mới)
- Phạm vi cung cấp theo khu vực: Toàn cầu. Các dự án có địa chỉ thanh toán ở EEA sẽ áp dụng Điều khoản dịch vụ của Google Maps Platform tại EEA (có hiệu lực từ ngày 8 tháng 7 năm 2025). Theo đó, bạn không được sử dụng nội dung của Places API (ngoại trừ vĩ độ, kinh độ và mã địa điểm) với bất kỳ bản đồ nào, trừ phi thông qua Places UI Kit. Thông tin tóm tắt về địa điểm, bài đánh giá và khu vực sử dụng AI chỉ được cung cấp bằng các ngôn ngữ và ở những khu vực được hỗ trợ.
Places API (Mới): trường hợp sử dụng
Sử dụng Places API (Mới) khi:
- Bạn cần tìm kiếm địa điểm từ một máy chủ bằng cụm từ tìm kiếm dạng văn bản (Tìm kiếm văn bản (Mới)) hoặc xung quanh một vị trí (Nearby Search (Mới)).
- Bạn cần có cụm từ gợi ý về địa điểm hoặc cụm từ tìm kiếm trước khi nhập từ một phần phụ trợ thông qua tính năng Tự động hoàn thành (Mới).
- Bạn có Mã địa điểm và cần thông tin chi tiết như địa chỉ, số điện thoại, điểm xếp hạng, bài đánh giá hoặc ảnh.
- Bạn cần có thông tin tóm tắt về địa điểm, bài đánh giá hoặc khu vực sử dụng AI cho một địa điểm.
Không sử dụng Places API (Mới) khi:
- Bạn đang xây dựng một ứng dụng Android gốc. Hãy sử dụng Places SDK cho Android.
- 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 xây dựng một ứng dụng web trên trình duyệt và muốn tải Thư viện địa điểm bằng JavaScript. Thay vào đó, hãy sử dụng Maps JavaScript API.
Places API (Mới): thiết lập
- Dịch vụ cần bật:
places.googleapis.com - Xác thực: Khoá API, OAuth 2.0
- Bắt đầu: Thiết lập Places API (Mới)
- Tài liệu tham khảo: Tài liệu tham khảo về Places API (Mới)
- Giá: Mức sử dụng và thanh toán cho Places API (Mới)
- Chính sách: Chính sách về Places API (Mới)
- Ghi chú phát hành: Ghi chú phát hành về Places API (Mới)
Các gói Places API (Mới) chính thức:
- npm:
@googlemaps/places - pypi:
google-maps-places - go:
cloud.google.com/go/maps
Places API (Mới): sản phẩm có liên quan
- Thay thế: Places API (Phiên bản cũ)
- Thường dùng với: Geocoding API, Routes API, Address Validation API
Places API (Mới): các lỗi thường gặp
- Vấn đề: Place Details (Mới), Nearby Search (Mới) và Tìm kiếm văn bản (Mới) không có danh sách trường trả về mặc định; các yêu cầu không có mặt nạ trường sẽ trả về lỗi. Cách khắc phục: Truyền mặt nạ trường phản hồi bằng tham số
fieldshoặc$fields, hoặc tiêu đềX-Goog-FieldMask. Xem /maps/documentation/places/web-service/choose-fields. - Vấn đề: Nếu mã phiên Tự động hoàn thành (Mới) bị bỏ qua hoặc được sử dụng lại sau khi một phiên kết thúc, thì mỗi yêu cầu sẽ được tính phí riêng dưới dạng SKU: Yêu cầu tự động hoàn thành. Cách khắc phục: Tạo một mã phiên mới (nên dùng UUID phiên bản 4) cho mỗi phiên và kết thúc phiên bằng yêu cầu Place Details (Mới) hoặc Xác thực địa chỉ. Xem /maps/documentation/places/web-service/place-session-tokens.
- Vấn đề: Mã hiện có hoặc mã do AI tạo gọi Places API (Phiên bản cũ) hoặc Maps JavaScript API
PlacesServicetrên một dự án chưa bật API cũ sẽ không thành công và trả về lỗiLegacyApiNotActivatedMapError. Cách khắc phục: Di chuyển các lệnh gọi sang Places API (Mới) và thêm mặt nạ trường bắt buộc. Hãy xem /maps/legacy#LegacyApiNotActivatedMapError. - Vấn đề: Mã địa điểm được lưu trữ có thể trở nên lỗi thời; sau đó, Chi tiết địa điểm (Mới) sẽ trả về
NOT_FOUND(HTTP 404) và mã nhận dạng không đúng định dạng hoặc bị cắt bớt sẽ trả về HTTP 400INVALID_ARGUMENT. Cách khắc phục: Làm mới mã địa điểm đã lưu trữ hơn 12 tháng bằng yêu cầu Chi tiết địa điểm (Mới) chỉ yêu cầu trườngid(không tính phí). Xem /maps/documentation/places/web-service/place-id#refresh-id.
Những việc bạn có thể làm với Places API (Mới)
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 API (Mới): 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 API (Mới): Đị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.
- 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ề URI để mở trang chỉ đường trong Google Maps cho một địa điểm.
- Trả về URI để mở trang viết bài đánh giá về một địa điểm trên Google Maps.
- Trả về URI để mở trang đọc bài đánh giá về một địa điểm trong Google Maps.
- Trả về URI để mở trang ảnh trong Google Maps cho một địa điểm.
- 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.