Trang này được dịch bởi Cloud Translation API.

Tìm kiếm lân cận (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

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 thông 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ởi GMSPlaceProperty. 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ạng GMSPlace với một đối tượng GMSPlace cho mỗi vị trí phù hợp.

Lưu ý: Các trường của đối tượng GMSPlace phản hồi không được để trống. Ví dụ: nếu danh sách trường bao gồm GMSPlacePropertyPhotos đến yêu cầu trường photos trong phản hồi và trường photos trong phản hồi trống, sẽ bị loại khỏi đối tượng GMSPlace phản hồi.

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ượng GMSPlaceSearchNearbyRequest. 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ường name 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 hình 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, includePrimaryTypes/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.

Lưu ý: Các giá trị trong Bảng B chỉ được trả về trong phản hồi. Bạn không thể sử dụng các giá trị trong Bảng B làm bộ lọc.

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ụng includedPrimaryTypes 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ụng includedTypes 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".

Nếu bạn bỏ qua includedTypes, excludedTypes, includedPrimaryTypes và excludedPrimaryTypes trong yêu cầu, thao tác tìm kiếm sẽ trả về địa điểm cho tất cả các loại trong giới hạn hạn chế về vị trí.

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ủa includedTypes 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ỗi INVALID_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ỗi INVALID_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ới regionCode, mã quốc gia bị bỏ khỏi formattedAddress. Thông số này không ảnh hưởng đến adrFormatAddress, tức là luôn bao gồm quốc gia tên hoặc trên shortFormattedAddress, 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ổ.

Tìm kiếm lân cận (Mới)

Yêu cầu Tìm kiếm lân cận (Mới)

Swift

Objective-C

GooglePlacesSwift

Phản hồi cho tính năng Tìm kiếm lân cận

Thông số bắt buộc

Danh sách trường

Swift

Objective-C

GooglePlacesSwift

locationRestriction

Thông số tùy chọn

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

Hiển thị thuộc tính trong ứng dụng của bạn