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 bởi 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 trả về một danh sách các địa điểm phù hợp, mỗi địa điểm được thể hiện bằng một
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 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 danh sách các loại địa điểm để bao gồm hoặc loại trừ một cách rõ ràng khỏi của bạn. Ví dụ: bạn có thể chỉ định chỉ đưa những địa điểm đó vào 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)
Đưa ra yêu cầu Tìm kiếm lân cận bằng cách gọi
GMSPlacesClient searchNearbyWithRequest:
!
truyền một
GMSPlaceSearchNearbyRequest
xác định các 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ả
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
GMSPlace
, còn được gọi là trường mặt nạ, như được xác định bởiGMSPlaceProperty
. 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í, 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ạ độ của địa điểm
(GMSPlacePropertyCoordinate
) cho mỗi đối tượng GMSPlace
trong tìm kiếm
kết quả. API này cũng lọc câu trả lờ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 cho tính năng Tìm kiếm lân cận
API Tìm kiếm lân cận trả về một mảng các kết quả trùng khớp ở dạngGMSPlace
với một đối tượng GMSPlace
cho mỗi vị trí phù hợ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:
-
isOpen
tính toán xem một địa điểm có mở cửa hay không tại thời điểm đã cho. 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 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 để trả về trong đối tượng
GMSPlace
cho địa điểm dưới dạng mặt nạ trường. Để xác định mặt nạ trường, chuyển một mảng các giá trị từGMSPlaceProperty
cho đối tượngGMSPlaceSearchNearbyRequest
. Tạo mặt nạ cho trường là một phương pháp thiết kế tốt để đả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:
Sau đây là các trường kích hoạt SKU của 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
Sau đây là các trường 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
Sau đây là các trường 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 truyền danh sách hai giá trị trường để chỉ định rằng đối tượng
GMSPlace
được yêu cầu trả về sẽ 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
GMSPlaceLocationRestriction
đố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 điểm giữa và bán kính tính theo mét. Bán kính phải nằm trong khoảng từ 0,0 đến 50000,0, bao gồm cả hai giá trị đó. Bán kính mặc định là 0,0. Bạn phải đặt giá trị này trong yêu cầu của mình thành một giá trị lớn hơn 0,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, includesPrimaryTypes/excludedPrimaryTypes
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 có loại chính cụ thể hơn đồng hồ hẹn giờ được chỉ định. Ví dụ: bạn chỉ định bao gồm loại chính"restaurant"
. Sau đó, câu trả lời có thể chứa địa điểm có loại chính là"restaurant"
, nhưng câu trả lời cũng có thể chứa những địa điểm có từ khoá cụ thể hơn loại chính, 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": ["restaurant"], "excludedPrimaryTypes": ["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"
.includedTypes
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.
excludedTypes
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
.includedPrimaryTypes
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.
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ả hai
includedPrimaryTypes
vàexcludedPrimaryTypes
, một thuộc tính Trả về lỗiINVALID_ARGUMENT
. -
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 1 và 20 (mặc định).
-
rankPreference
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.
-
regionCode
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
. Thông số này không ảnh hưởng đếnadrFormatAddress
, tức là luôn bao gồm quốc gia tên hoặc trênshortFormattedAddress
, mà không bao giờ có tên đó.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ả.
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ừ
GMSPlacesClient
!
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.
Ví dụ: thuộc tính reviews
của đối tượng GMSPlacesClient
chứa một mảng tối đa năm
GMSPlaceReview
. Mỗi đối tượng GMSPlaceReview
có thể chứa thông tin ghi nhận sự đóng góp và thông tin ghi nhận tác giả.
Nếu hiển thị bài đánh giá trong ứng dụng của mình, thì bạn cũng phải hiển thị mọi thuộc tính hoặc tác giả
phân bổ giá trị đóng góp.
Để biết thêm thông tin, hãy xem tài liệu về phân bổ.