Yêu cầu Tìm kiếm lân cận (Mới) nhập khu vực
để tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định theo vĩ độ và kinh độ
toạ độ của tâm điểm giữa đường tròn và bán kính tính bằng mét. Chiến lược phát hành đĩa đơn
yêu cầu trả về danh sách các địa điểm phù hợp, mỗi địa điểm được thể hiện bằng một
Place
trong khu vực tìm kiếm được 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ể lọc câu trả lời nếu muốn bằng cách chỉ định một danh sách loại địa điểm cho thêm vào hoặc loại trừ một cách rõ ràng khỏi câu trả lời. Ví dụ: bạn có thể chỉ định để chỉ bao gồm những địa điểm đó trong câu trả lời thuộc loại "nhà hàng", "tiệm bánh" và "quán cà phê" hoặc loại trừ tất 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 một
SearchNearbyRequest
xác định các tham số yêu cầu.
Đối tượng SearchNearbyRequest
chỉ định tất cả các thông tin 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 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í đối với khu vực tìm kiếm, được định nghĩa là 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
chứa các trường địa điểm Place.Field.ID
và Place.Field.NAME
cho mỗi trường
Place
đối tượng trong kết quả tìm kiếm. Thao tác này cũng lọc câu trả lời để chỉ
trả lại đị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à "american_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)
Chiến lược phát hành đĩa đơn
SearchNearbyResponse
thể hiện phản hồi từ một yêu cầu tìm kiếm. Một SearchNearbyResponse
đối tượng 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 địa điểmPlace
đối tượng cho mỗi địa điểm phù hợ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 chuyể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 phù hợp. Sau đó, bạn có thể dùng Place.getId()
và phương thức 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 địa điểm
trường dữ liệu đối tượng.
Thông số bắt buộc
Sử dụng
SearchNearbyRequest
để chỉ định các tham số bắt buộc cho tìm kiếm.
Danh sách trường
Khi bạn 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 làm 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
cho đối tượngSearchNearbyRequest
. Tạo mặt nạ cho trường là một phương pháp thiết kế hay để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, điều này 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 tính năng Tìm kiếm lân cận (Cơ bản) SKU:
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 tính năng Tìm kiếm lân cận (Nâng cao) SKU:
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 tính năng Tìm kiếm lân cận (Được ưu tiên) SKU:
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ị của trường để chỉ định rằng Đối tượng
Place
được yêu cầu trả về chứaPlace.Field.ID
và TrườngPlace.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í
Đáp
LocationRestriction
đối tượng xác định vùng cần tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định bởi tâm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng lớn hơn 0,0 và nhỏ hơn hoặc bằng 50000.0, xin lưu ý rằng việc chỉ định bán kính quá nhỏ sẽ trả vềZERO_RESULTS
làm phản hồi.Để đặt thông số hạn chế vị trí, hãy thực hiện lệnh gọi
setLocationRestriction()
khi tạo đối tượngSearchNearbyRequest
.
Thông số tùy chọn
Sử dụng
SearchNearbyRequest
để chỉ định các tham số không bắt buộc cho nội dung 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 duy nhất trong các loại Bảng A được liên kết với nó. Ví dụ: loại chính có thể là
"mexican_restaurant"
hoặc"steak_house"
. Sử dụngincludedPrimaryTypes
vàexcludedPrimaryTypes
để lọc kết quả loại hình 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 liên kết với cuộc trò chuyện đó. Ví dụ: một nhà hàng có thể có các loại sau:
"seafood_restaurant"
,"restaurant"
,"food"
"establishment"
,"point_of_interest"
. Sử dụngincludedTypes
vàexcludedTypes
để lọc kết quả trên danh sách các loại được liên kết với một địa điểm.Khi bạn chỉ định một loại chính chung, chẳng hạn như
"restaurant"
hoặc"hotel"
, câu trả lời có thể chứa các địa điểm với loại chính cụ thể khác với loại được chỉ định. Ví dụ: bạn chỉ định bao gồm loại chính của"restaurant"
. Sau đó, phản hồi có thể chứa các địa điểm có loại chính là"restaurant"
, nhưng loại câu trả lời cũng có thể chứa các địa điểm có loại chính cụ thể hơn, chẳng hạn như"chinese_restaurant"
hoặc"seafood_restaurant"
.Nếu nội dung tìm kiếm được chỉ định với hạn chế nhiều loại, thì chỉ địa điểm đáp ứng tất cả các hạn chế sẽ được trả về. Ví dụ: nếu bạn chỉ định
includedTypes = Arrays.asList("restaurant")
vàexcludedPrimaryTypes = Arrays.asList("steak_house")
, địa điểm được trả lại cung cấp"restaurant"
dịch vụ liên quan 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 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 từ 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ố các 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 từ Bảng A để loại trừ khỏi 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ì hàm này câu trả lời bao gồm các địa điểm được phân loại là"school"
nhưng không phải là"primary_school"
. Câu trả lời bao gồm các địa điểm khớp với ít nhất một củaincludedTypes
và không có mục 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ì hệ thống sẽ trả về lỗiINVALID_REQUEST
.Để đặ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 từ Bảng A cần bao gồm trong một 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 từ Bảng A để loại trừ khỏi một lượt tìm kiếm.
Nếu có bất kỳ loại chính nào xung đột với nhau, chẳng hạn như một loại xuất hiện trong cả hai
includedPrimaryTypes
vàexcludedPrimaryTypes
, một thuộc tính Trả về lỗiINVALID_ARGUMENT
.Để đặ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ề. Giá trị phải nằm trong khoảng 1 và 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í được 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 làm mã CLDR gồm 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
, mã quốc gia bị bỏ khỏiformattedAddress
.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à "Vương quốc Anh" (.co.uk) trong khi mã ISO 3166-1 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "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 ứng dụng của bạn hiển thị thông tin thu được từ
PlacesClient
!
chẳng hạn như ảnh và bài đánh giá, thì ứng dụng cũng phải cho thấy các thông tin ghi nhận sự đóng góp cần thiết.
Để 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.