Tài liệu tham khảo nhanh về Places API (Mới)

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

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): 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ố fields hoặ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 PlacesService trên một dự án chưa bật API cũ sẽ không thành công và trả về lỗi LegacyApiNotActivatedMapError. 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 400 INVALID_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ường id (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

Places API (Mới): Địa điểm