Yêu cầu Tìm kiếm lân cận (Mới) lấy thông tin nhập vào khu vực để tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định bằng toạ độ theo vĩ độ và kinh độ của điểm giữa của vòng tròn và bán kính tính bằng mét. Yêu cầu sẽ trả về một danh sách các địa điểm phù hợp, mỗi địa điểm được biểu thị bằng một đối tượng Place
, trong khu vực tìm kiếm đã chỉ định.
Theo mặc định, câu trả lời sẽ chứa mọi loại địa điểm thuộc khu vực tìm kiếm. Bạn có thể tuỳ ý lọc phản hồi bằng cách chỉ định một danh sách các loại địa điểm để đưa vào hoặc loại trừ một cách rõ ràng khỏi phản hồi. Ví dụ: bạn có thể chỉ định chỉ bao gồm những địa điểm thuộc loại "nhà hàng", "tiệm bánh" và "quán cà phê" trong câu trả lời hoặc loại trừ tất cả các địa điểm thuộc loại "trường học".
Yêu cầu Tìm kiếm lân cận (Mới)
Thực hiện yêu cầu Tìm kiếm lân cận (Mới) bằng cách gọi PlacesClient.searchNearby
, truyền đối tượng SearchNearbyRequest
xác định các tham số yêu cầu.
Đối tượng SearchNearbyRequest
chỉ định tất cả các tham số bắt buộc và không bắt buộc cho yêu cầu. Các tham số bắt buộc bao gồm:
- Danh sách các trường cần trả về trong đối tượng
Place
(còn được gọi là mặt nạ trường). Nếu bạn không chỉ định ít nhất một trường trong danh sách trường hoặc nếu bạn bỏ qua danh sách trường, thì lệnh gọi sẽ trả về lỗi. - Hạn chế vị trí cho khu vực tìm kiếm, được xác định bằng một cặp vĩ độ/kinh độ và giá trị bán kính tính bằng mét.
Ví dụ về yêu cầu tìm kiếm lân cận này chỉ định rằng các đối tượng Place
phản hồi có chứa các trường địa điểm Place.Field.ID
và Place.Field.NAME
cho từng đối tượng Place
trong kết quả tìm kiếm. Bộ lọc này cũng lọc phản hồi để chỉ trả về các địa điểm thuộc loại "nhà hàng" và "quán cà phê", nhưng loại trừ các địa điểm thuộc loại "pizza_nhà hàng" và "Mỹ_nhà hàng".
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Define the search area as a 1000 meter diameter circle in New York, NY. LatLng center = new LatLng(40.7580, -73.9855); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000); // Define a list of types to include. final List<String> includedTypes = Arrays.asList("restaurant", "cafe"); // Define a list of types to exclude. final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant"); // Use the builder to create a SearchNearbyRequest object. final SearchNearbyRequest searchNearbyRequest = SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields) .setIncludedTypes(includedTypes) .setExcludedTypes(excludedTypes) .setMaxResultCount(10) .build()); // Call placesClient.searchNearby() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchNearby(searchNearbyRequest) .addOnSuccessListener(response -> { List<Place> places = response.getPlaces(); });
Câu trả lời cho tính năng Tìm kiếm lân cận (Mới)
Lớp SearchNearbyResponse
thể hiện phản hồi từ một yêu cầu tìm kiếm. Đối tượng SearchNearbyResponse
chứa:
- Danh sách đối tượng
Place
đại diện cho tất cả địa điểm trùng khớp, trong đó có một đối tượngPlace
cho mỗi địa điểm trùng khớp. - Mỗi đối tượng
Place
chỉ chứa các trường được xác định bằng danh sách trường được truyền trong yêu cầu.
Ví dụ: trong yêu cầu, bạn đã xác định một danh sách trường là:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
Danh sách trường này có nghĩa là mỗi đối tượng Place
trong phản hồi chỉ chứa mã địa điểm và tên của từng địa điểm trùng khớp. Sau đó, bạn có thể dùng các phương thức Place.getId()
và Place.getName()
để truy cập vào các trường này trong từng đối tượng Place
.
Để biết thêm ví dụ về cách truy cập dữ liệu trong đối tượng Place
, hãy xem bài viết Truy cập vào các trường dữ liệu đối tượng Địa điểm.
Thông số bắt buộc
Sử dụng đối tượng SearchNearbyRequest
để chỉ định các tham số bắt buộc cho hoạt động tìm kiếm.
Danh sách trường
Khi yêu cầu thông tin chi tiết về địa điểm, bạn phải chỉ định dữ liệu cần trả về trong đối tượng
Place
cho địa điểm dưới dạng mặt nạ trường. Để xác định mặt nạ trường, hãy truyền một mảng giá trị từPlace.Field
sang đối tượngSearchNearbyRequest
. Tạo mặt nạ trường là một phương pháp thiết kế hiệu quả để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và các khoản phí thanh toán không cần thiết.Chỉ định một hoặc nhiều trường sau:
Các trường sau đây kích hoạt SKU của tính năng Tìm kiếm lân cận (Cơ bản):
Place.Field.ADDRESS_COMPONENTS
,Place.Field.BUSINESS_STATUS
,Place.Field.ADDRESS
,Place.Field.ICON_BACKGROUND_COLOR
,Place.Field.ICON_URL
,Place.Field.LAT_LNG
,Place.Field.PHOTO_METADATAS
,Place.Field.PLUS_CODE
,Place.Field.ID
,Place.Field.NAME
,Place.Field.TYPES
,Place.Field.UTC_OFFSET
,Place.Field.VIEWPORT
,Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
Các trường sau đây kích hoạt SKU của tính năng Tìm kiếm lân cận (Nâng cao):
Place.Field.CURRENT_OPENING_HOURS
,Place.Field.SECONDARY_OPENING_HOURS
,Place.Field.PHONE_NUMBER
,Place.Field.PRICE_LEVEL
,Place.Field.RATING
,Place.Field.OPENING_HOURS
,Place.Field.USER_RATINGS_TOTAL
,Place.Field.WEBSITE_URI
Các trường sau đây kích hoạt SKU của tính năng Tìm kiếm lân cận (Ưu tiên):
Place.Field.CURBSIDE_PICKUP
,Place.Field.DELIVERY
,Place.Field.DINE_IN
,Place.Field.EDITORIAL_SUMMARY
,Place.Field.RESERVABLE
,Place.Field.REVIEWS
,Place.Field.SERVES_BEER
,Place.Field.SERVES_BREAKFAST
,Place.Field.SERVES_BRUNCH
,Place.Field.SERVES_DINNER
,Place.Field.SERVES_LUNCH
,Place.Field.SERVES_VEGETARIAN_FOOD
,Place.Field.SERVES_WINE
,Place.Field.TAKEOUT
Để đặt tham số danh sách trường, hãy gọi phương thức
setPlaceFields()
khi tạo đối tượngSearchNearbyRequest
.Ví dụ sau đây xác định danh sách hai giá trị trường để chỉ định rằng đối tượng
Place
do yêu cầu trả về sẽ chứa các trườngPlace.Field.ID
vàPlace.Field.NAME
:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
Hạn chế vị trí
Đối tượng
LocationRestriction
xác định khu vực cần tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định bằng điểm giữa và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0,0 đến nhỏ hơn hoặc bằng 50000, lưu ý rằng việc chỉ định bán kính quá nhỏ sẽ trả vềZERO_RESULTS
dưới dạng phản hồi.Để đặt tham số hạn chế về vị trí, hãy gọi phương thức
setLocationRestriction()
khi tạo đối tượngSearchNearbyRequest
.
Thông số tùy chọn
Sử dụng đối tượng SearchNearbyRequest
để chỉ định các tham số không bắt buộc cho hoạt động tìm kiếm.
-
Loại và loại chính
Cho phép bạn chỉ định danh sách các loại trong các loại Bảng A dùng để lọc kết quả tìm kiếm. Bạn có thể chỉ định tối đa 50 loại trong mỗi danh mục hạn chế loại.
Một địa điểm chỉ có thể có một loại chính trong các loại Bảng A liên kết với địa điểm đó. Ví dụ: loại chính có thể là
"mexican_restaurant"
hoặc"steak_house"
. Hãy sử dụngincludedPrimaryTypes
vàexcludedPrimaryTypes
để lọc kết quả theo loại chính của một địa điểm.Một địa điểm cũng có thể có nhiều giá trị loại từ các loại Bảng A được liên kết với địa điểm đó. Ví dụ: một nhà hàng có thể có những loại sau:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Hãy sử dụngincludedTypes
vàexcludedTypes
để lọc kết quả theo danh sách các loại liên kết với một địa điểm.Nếu một lượt tìm kiếm được chỉ định với nhiều hạn chế về loại, thì chỉ những vị trí đáp ứng tất cả các hạn chế đó mới được trả về. Ví dụ: nếu bạn chỉ định
includedTypes = Arrays.asList("restaurant")
vàexcludedPrimaryTypes = Arrays.asList("steak_house")
, thì các vị trí được trả về cung cấp các dịch vụ liên quan đến"restaurant"
nhưng không hoạt động chủ yếu dưới dạng"steak_house"
.Để biết ví dụ về cách sử dụng
includedTypes
vàexcludedTypes
, hãy xem bài viết Yêu cầu Tìm kiếm lân cận (Mới).Các loại được bao gồm
Danh sách các loại địa điểm trong Bảng A để tìm kiếm. Nếu tham số này bị bỏ qua, hàm sẽ trả về tất cả các loại địa điểm.
Để đặt tham số loại được đưa vào, hãy gọi phương thức
setIncludedTypes()
khi tạo đối tượngSearchNearbyRequest
.Các loại bị loại trừ
Danh sách các loại địa điểm trong Bảng A để loại trừ khỏi kết quả tìm kiếm.
Nếu bạn chỉ định cả
includedTypes
(chẳng hạn như"school"
) vàexcludedTypes
(chẳng hạn như"primary_school"
) trong yêu cầu, thì phản hồi sẽ bao gồm các vị trí được phân loại là"school"
chứ không phải là"primary_school"
. Phản hồi bao gồm các vị trí khớp với ít nhất một trong sốincludedTypes
và không có vị trí nào trong sốexcludedTypes
.Nếu có bất kỳ loại xung đột nào, chẳng hạn như một loại xuất hiện trong cả
includedTypes
vàexcludedTypes
, thì lỗiINVALID_REQUEST
sẽ được trả về.Để đặt tham số các loại bị loại trừ, hãy gọi phương thức
setExcludedTypes()
khi tạo đối tượngSearchNearbyRequest
.Loại hình chính được bao gồm
Danh sách các loại địa điểm chính trong Bảng A để đưa vào nội dung tìm kiếm.
Để đặt tham số loại chính đi kèm, hãy gọi phương thức
setIncludedPrimaryTypes()
khi tạo đối tượngSearchNearbyRequest
.Loại chính bị loại trừ
Danh sách các loại địa điểm chính trong Bảng A cần loại trừ khỏi kết quả tìm kiếm.
Nếu có bất kỳ kiểu chính nào xung đột, chẳng hạn như một kiểu xuất hiện trong cả
includedPrimaryTypes
vàexcludedPrimaryTypes
, thì lỗiINVALID_ARGUMENT
sẽ được trả về.Để đặt tham số kiểu chính bị loại trừ, hãy gọi phương thức
setExcludedPrimaryTypes()
khi tạo đối tượngSearchNearbyRequest
. -
Số kết quả tối đa
Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Phải nằm trong khoảng từ 1 đến 20 (mặc định).
Để đặt thông số số lượng kết quả tối đa, hãy gọi phương thức
setMaxResultCount()
khi tạo đối tượngSearchNearbyRequest
. -
Tùy chọn xếp hạng
Loại thứ hạng sẽ sử dụng. Nếu tham số này bị bỏ qua, các kết quả được xếp hạng theo mức độ phổ biến. Có thể là một trong những trạng thái sau:
POPULARITY
(mặc định) Sắp xếp kết quả dựa trên mức độ phổ biến.DISTANCE
Sắp xếp các kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí đã chỉ định.
Để đặt tham số lựa chọn ưu tiên về thứ hạng, hãy gọi phương thức
setRankPreference()
khi tạo đối tượngSearchNearbyRequest
. -
Mã vùng
Mã vùng dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị mã CLDR hai ký tự. Không có giá trị mặc định.
Nếu tên quốc gia của trường
formattedAddress
trong phản hồi khớp vớiregionCode
, thì mã quốc gia sẽ bị bỏ qua trongformattedAddress
.Hầu hết mã CLDR đều giống với mã ISO 3166-1, với một số ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của mã này là "gb" (về mặt kỹ thuật là "Vương quốc Anh" và Bắc Ireland). Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả.
Để đặt tham số mã khu vực, hãy gọi phương thức
setRegionCode()
khi tạo đối tượngSearchNearbyRequest
.
Hiển thị thuộc tính trong ứng dụng của bạn
Khi hiển thị thông tin thu được từ PlacesClient
, chẳng hạn như ảnh và bài đánh giá, ứng dụng cũng phải cho thấy các thuộc tính bắt buộc.
Để biết thêm thông tin, hãy xem Chính sách dành cho SDK địa điểm dành cho Android.