Yêu cầu Tìm kiếm lân cận (Mới) sử dụng dữ liệu đầu vào để tìm kiếm khu vực được chỉ định dưới dạng vòng tròn, được xác định theo toạ độ vĩ độ và kinh độ của điểm tâm của vòng tròn và bán kính tính bằng mét. Yêu cầu này 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 GMSPlace
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 trong khu vực tìm kiếm. Bạn có thể tuỳ ý lọc phản hồi bằng cách chỉ định danh sách các loại địa điểm để đưa vào hoặc loại trừ khỏi phản hồi một cách rõ ràng. Ví dụ: bạn có thể chỉ định để chỉ bao gồm các đị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ả 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 bằng cách gọi GMSPlacesClient searchNearbyWithRequest:
, truyền đối tượng GMSPlaceSearchNearbyRequest
xác định tham số yêu cầu và phương thức gọi lại thuộc loại GMSPlaceSearchNearbyResultCallback
để xử lý phản hồi.
Đối tượng GMSPlaceSearchNearbyRequest
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
GMSPlace
, còn gọi là mặt nạ trường, doGMSPlaceProperty
xác định. 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ề một lỗi. - Giới hạn vị trí, nghĩa là vòng tròn xác định khu vực tìm kiếm.
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 GMSPlace
phản hồi chứa tên địa điểm (GMSPlacePropertyName
) và toạ độ địa điểm (GMSPlacePropertyCoordinate
) cho từng đối tượng GMSPlace
trong kết quả tìm kiếm. Thao tá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ê".
Swift
// Array to hold the places in the response var placeResults: [GMSPlace] = [] // Define the search area as a 500 meter diameter circle in San Francisco, CA. let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500) // Specify the fields to return in the GMSPlace object for each place in the response. let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue} // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties) let includedTypes = ["restaurant", "cafe"] request.includedTypes = includedTypes let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } placeResults = results } GMSPlacesClient.shared().searchNearby(with: request, callback: callback)
Objective-C
// Array to hold the places in the response _placeResults = [NSArray array]; // Define the search area as a 500 meter diameter circle in San Francisco, CA. id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500); // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc] initWithLocationRestriction:circularLocation placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]]; // Set the place types to filter on. NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ]; request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes]; [_placesClient searchNearbyWithRequest:request callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { // Get list of places. _placeResults = places; } } ];
GooglePlacesSwift
let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500) let searchNearbyRequest = SearchNearbyRequest( locationRestriction: restriction, placeProperties: [ .name, .coordinate], includedTypes: [ .restaurant, .cafe ], ) switch await placesClient.searchNearby(with: searchNearbyRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Phản hồi về Tìm kiếm lân cận
API Tìm kiếm lân cận trả về một loạt các kết quả trùng khớp ở dạng các đối tượngGMSPlace
, với một đối tượng GMSPlace
cho mỗi vị trí trùng khớp.
Cùng với các trường dữ liệu, đối tượng GMSPlace
trong phản hồi chứa các hàm thành phần sau đây:
-
isOpen
tính toán xem một địa điểm có mở cửa vào thời gian nhất định hay không. isOpenAtDate
tính toán xem một địa điểm có mở cửa vào một ngày nhất định hay không.
Thông số bắt buộc
Sử dụng đối tượng GMSPlaceSearchNearbyRequest
để chỉ định các tham số bắt buộc cho nội dung 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
GMSPlace
cho địa điểm dưới dạng mặt nạ trường (field mask). Để xác định mặt nạ trường (field mask), hãy truyền một mảng các giá trị từGMSPlaceProperty
đến đối tượngGMSPlaceSearchNearbyRequest
. Che giấu trường là một phương pháp thiết kế hiệu quả để đảm bảo 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à chi 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 sẽ kích hoạt SKU của tính năng Tìm kiếm lân cận (Cơ bản):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyCoordinate
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyName
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlaceID
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
Các trường sau đây sẽ kích hoạt SKU của tính năng Tìm kiếm lân cận (Nâng cao):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
Các trường sau đây sẽ kích hoạt SKU của tính năng Tìm kiếm lân cận (Ưu tiên):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
Ví dụ sau đây chuyển một danh sách hai giá trị trường để chỉ định rằng đối tượng
GMSPlace
do một yêu cầu trả về chứa các trườngname
vàplaceID
:Swift
// Specify the place data types to return. let fields: [GMSPlaceProperty] = [.placeID, .name]
Objective-C
// Specify the place data types to return. NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
-
locationRestriction
Một đối tượng
GMSPlaceLocationRestriction
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 theo đ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 50000,0. Bán kính mặc định là 0. Bạn phải đặt tham số này trong yêu cầu của mình thành một giá trị lớn hơn 0.
Thông số tùy chọn
Sử dụng đối tượng GMSPlaceSearchNearbyRequest
để chỉ định các tham số không bắt buộc cho nội dung tìm kiếm.
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Cho phép bạn chỉ định danh sách các loại thuộ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ế về loại.
Một địa điểm chỉ có thể có một loại chính trong số các loại Bảng A được 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ả về loại địa điểm chính.Một địa điểm cũng có thể có nhiều giá trị loại trong số các loại Bảng A liên kết với địa điểm đó. Ví dụ: một nhà hàng có thể có các loại sau:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Sử dụngincludedTypes
vàexcludedTypes
để lọc kết quả trong danh sách các loại liên kết với một địa điểm.Nếu một cụm từ tìm kiếm được chỉ định kèm theo nhiều lựa chọn hạn chế về loại, thì hệ thống chỉ trả về những địa điểm đáp ứng tất cả hạn chế này. Ví dụ: nếu bạn chỉ định
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, thì các địa điểm được trả về sẽ 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"
.includedTypes
Danh sách các loại địa điểm từ Bảng A cần tìm. Nếu tham số này bị bỏ qua, hàm sẽ trả về các địa điểm thuộc tất cả các loại.
excludedTypes
Danh sách các loại địa điểm từ 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 trongincludedTypes
và không có nơi nào trongexcludedTypes
.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ề.includedPrimaryTypes
Danh sách các loại địa điểm chính trong Bảng A để đưa vào lượt tìm kiếm.
excludedPrimaryTypes
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ả
includedPrimaryTypes
vàexcludedPrimaryTypes
, thì lỗiINVALID_ARGUMENT
sẽ được trả về. -
maxResultCount
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 từ 1 đến 20 (mặc định).
-
rankPreference
Loại xếp hạng sẽ sử dụng. Nếu thông số này bị bỏ qua, thì các kết quả sẽ đượ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.
-
regionCode
Mã vùng dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị 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
, thì mã quốc gia sẽ bị loại khỏiformattedAddress
. Tham số này không ảnh hưởng đếnadrFormatAddress
(luôn bao gồm tên quốc gia) hoặc đối vớishortFormattedAddress
(không bao giờ bao gồm tên quốc gia).Hầu hết các mã CLDR đều giống hệt với mã ISO 3166-1, trừ một số trường hợp 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 là "gb" (về mặt kỹ thuật, là pháp nhân của "Vương quốc Anh và Bắc Ireland"). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
Hiển thị thuộc tính trong ứng dụng của bạn
Khi hiện thông tin thu thập được từ GMSPlacesClient
, 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.
Ví dụ: thuộc tính reviews
của đối tượng GMSPlacesClient
chứa một mảng gồm tối đa 5 đối tượng GMSPlaceReview
. Mỗi đối tượng GMSPlaceReview
có thể chứa các thuộc tính và tác giả.
Nếu hiển thị bài đánh giá trong ứng dụng của mình, bạn cũng phải hiển thị mọi ghi công hoặc tác giả.
Để biết thêm thông tin, vui lòng xem tài liệu về mô hình phân bổ.