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) 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, do GMSPlaceProperty 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ượng GMSPlace, 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ượng GMSPlaceSearchNearbyRequest. 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ườ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

    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ụng includedPrimaryTypes 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ụng includedTypes 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 trong includedTypes và không có nơi nào trong 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ỗi INVALID_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ỗi INVALID_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ới regionCode, thì mã quốc gia sẽ bị loại khỏi formattedAddress. Tham số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia) hoặc đối với shortFormattedAddress (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ổ.