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) lấy dữ liệu đầu vào là 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 bằng toạ độ vĩ độ và kinh độ của tâm vòng tròn và bán kính tính bằng mét. Yêu cầu này trả về danh sách các địa điểm trùng khớp, mỗi địa điểm được biểu thị bằng một đối tượng GMSPlace trong phạm vi tìm kiếm đã chỉ định.

Theo mặc định, phản hồi chứa tất cả các 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. Ví dụ: bạn có thể chỉ định chỉ đưa những địa điểm thuộc loại "nhà hàng", "tiệm bánh" và "quán cà phê" vào nội dung phản hồi, 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)

Tạo 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 các tham số yêu cầu và một 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ề lỗi.
  • Hạn chế về vị trí, nghĩa là vòng tròn xác định khu vực tìm kiếm.

Yêu cầu tìm kiếm địa điểm lân cận mẫu 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 mỗi đối tượng GMSPlace trong kết quả tìm kiếm. Hàm này cũng lọc phản hồi để chỉ trả về những địa điểm thuộc loại "nhà hàng" và "quán cà phê".

SDK Places Swift

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
}

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;
    }
  }
];

Nội dung phản hồi của Nearby Search

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 đối tượng GMSPlace, trong đó mỗi địa điểm trùng khớp có một đối tượng GMSPlace.

Lấy trạng thái đang mở

Đối tượng GMSPlacesClient chứa một hàm thành viên có tên là isOpenWithRequest (isOpenRequest trong Swift và isPlaceOpenRequest trong GooglePlacesSwift) trả về phản hồi cho biết liệu địa điểm đó có đang mở cửa hay không, dựa trên thời gian được chỉ định trong lệnh gọi.

Phương thức này nhận một đối số duy nhất thuộc loại GMSPlaceIsOpenWithRequest chứa:

  • Một đối tượng GMSPlace hoặc một chuỗi chỉ định mã địa điểm. Để biết thêm thông tin về cách tạo đối tượng Địa điểm bằng các trường cần thiết, hãy xem phần Thông tin chi tiết về địa điểm.
  • Đối tượng NSDate (Obj-C) hoặc Date (Swift) không bắt buộc, chỉ định thời gian bạn muốn kiểm tra. Nếu bạn không chỉ định thời gian, thời gian mặc định sẽ là hiện tại.
  • Phương thức GMSPlaceOpenStatusResponseCallback để xử lý phản hồi.
    • >

Phương thức GMSPlaceIsOpenWithRequest yêu cầu bạn phải đặt các trường sau trong đối tượng GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Nếu các trường này không được cung cấp trong đối tượng Địa điểm hoặc nếu bạn truyền mã địa điểm, thì phương thức này sẽ sử dụng GMSPlacesClient GMSFetchPlaceRequest: để tìm nạp các trường đó.

Phản hồi isOpenWithRequest

isOpenWithRequest trả về một đối tượng GMSPlaceIsOpenResponse chứa giá trị boolean có tên status cho biết doanh nghiệp đang mở cửa, đóng cửa hay trạng thái không xác định.

Ngôn ngữ Giá trị nếu mở Giá trị nếu đóng Giá trị nếu trạng thái không xác định
Swift Places true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Thông tin thanh toán cho isOpenWithRequest

Ví dụ: Tạo yêu cầu GMSPlaceIsOpenWithRequest

Ví dụ sau đây cho thấy cách khởi tạo GMSPlaceIsOpenWithRequest trong một đối tượng GMSPlace hiện có.

SDK Places Swift

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

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 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. Để xác định mặt nạ trường, hãy truyền một mảng giá trị từ GMSPlaceProperty đến đối tượng GMSPlaceSearchNearbyRequest. Việc che trường là một phương pháp thiết kế hiệu quả để đả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í 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 Tìm kiếm lân cận Pro:

      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 Tìm kiếm ở lân cận dành cho doanh nghiệp:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Các trường sau đây sẽ kích hoạt SKU Tìm kiếm lân cận Enterprise Plus:

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

    Ví dụ sau đây truyền danh sách gồm hai giá trị trường để chỉ định rằng đối tượng GMSPlace do yêu cầu trả về chứa các trường name và placeID:

    SDK Places Swift

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

    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];

  • locationRestriction

    Đố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 bằng tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0 đến 50000. Bán kính mặc định là 0. Bạn phải đặt giá trị này trong yêu cầu 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 tìm kiếm.

  • includedTypes/excludedTypes, includedPrimaryTypes/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 quy định hạn chế về loại.

    Một địa điểm chỉ có thể có một loại chính trong các loại Bảng A liên kết với địa điểm đó. 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ả theo loại chính của đị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 đị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.

    Khi bạn chỉ định một loại chính chung, chẳng hạn như "restaurant" hoặc "hotel", phản hồi có thể chứa các địa điểm có loại chính cụ thể hơn so với loại đã chỉ định. Ví dụ: bạn chỉ định thêm một loại chính là "restaurant". Sau đó, phản hồi có thể chứa các địa điểm có loại chính là "restaurant", nhưng phản hồ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 một nội dung tìm kiếm được chỉ định với nhiều quy định hạn chế về loại, thì hệ thống sẽ chỉ trả về những địa điểm đáp ứng tất cả các quy định hạn chế đó. 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 trong Bảng A để tìm kiếm. Nếu bạn bỏ qua tham số này, hệ thống sẽ trả về tất cả các địa điểm.

    excludedTypes

    Danh sách các loại địa điểm trong 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 những địa điểm được phân loại là "school" nhưng không phải là "primary_school". Phản hồi bao gồm những địa điểm khớp với ít nhất một trong số includedTypes và không có địa điểm nào khớp với excludedTypes.

    Nếu có bất kỳ loại nào xung đột, 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 nội dung tìm kiếm.

    excludedPrimaryTypes

    Danh sách các loại địa điểm chính trong Bảng A để loại trừ khỏi kết quả tìm kiếm.

    Nếu có bất kỳ loại chính nào xung đột, 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ề. Phải nằm trong khoảng từ 1 đến 20 (mặc định).

  • rankPreference

    Loại thứ hạng cần sử dụng. Nếu bạn bỏ qua thông số này, kết quả sẽ được sắp xếp theo mức độ phổ biến. Có thể là một trong những loạ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 kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí đã chỉ định.

  • regionCode

    Mã khu vực 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ị bỏ qua khỏi formattedAddress. Thông số này không ảnh hưởng đến adrFormatAddress (luôn bao gồm tên quốc gia) hoặc shortFormattedAddress (không bao giờ bao gồm tên quốc gia).

    Hầu hết mã CLDR giống hệt với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD 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à cho thực thể "Vương quốc Anh và Bắc Ireland"). Thông 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ị thông tin phân bổ trong ứng dụng

Khi hiển thị thông tin thu được từ GMSPlacesClient, chẳng hạn như ảnh và bài đánh giá, ứng dụng của bạn cũng phải hiển thị các thông tin ghi công 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à thuộc tính tác giả. Nếu hiển thị bài đánh giá trong ứng dụng, thì bạn cũng phải hiển thị mọi thông tin ghi công hoặc thông tin ghi công tác giả.

Để biết thêm thông tin, hãy xem tài liệu về thuộc tính phân bổ.