Nearby Search (新版)

選取平台： Android iOS JavaScript 網頁服務
歐洲經濟區 (EEA) 開發人員

Nearby Search (新版) 要求會將要搜尋的區域做為輸入內容，並以圓形指定，該圓形由圓心的經緯度座標和半徑 (以公尺為單位) 定義。要求會傳回符合條件的地點清單，每個地點都以指定搜尋範圍內的 GMSPlace 物件表示。

根據預設，回應會包含搜尋區域內的所有類型地點。您可以選擇指定要明確納入或排除在回應中的地點類型清單，藉此篩選回應。舉例來說，您可以指定回應中僅包含「餐廳」、「麵包店」和「咖啡廳」類型的地點，或是排除所有「學校」類型的地點。

Nearby Search (新版) 要求

呼叫 GMSPlacesClient searchNearbyWithRequest:，傳遞定義要求參數的 GMSPlaceSearchNearbyRequest 物件和 GMSPlaceSearchNearbyResultCallback 類型的回呼方法，藉此提出「附近搜尋」要求，以處理回應。

GMSPlaceSearchNearbyRequest 物件會指定要求的所有必要和選用參數。必要參數包括：

  • 要在 GMSPlace 物件中傳回的欄位清單，也稱為欄位遮罩，如 GMSPlaceProperty 所定義。如果您未在欄位清單中指定至少一個欄位，或是省略欄位清單，呼叫作業就會傳回錯誤。
  • 地點限制，也就是定義搜尋區域的圓圈。

這個 Nearby Search 要求範例指定回應 GMSPlace 物件包含搜尋結果中每個 GMSPlace 物件的地點名稱 (GMSPlacePropertyName) 和地點座標 (GMSPlacePropertyCoordinate)。此外，這項要求也會篩選回應，只傳回「餐廳」和「咖啡廳」類型的地點。

Places Swift SDK

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

Nearby Search 回應

Nearby Search API 會以 GMSPlace 物件的形式傳回相符項目陣列，每個相符地點對應一個 GMSPlace 物件。

取得營業狀態

GMSPlacesClient 物件包含名為 isOpenWithRequest 的成員函式 (在 Swift 中為 isOpenRequest，在 GooglePlacesSwift 中為 isPlaceOpenRequest)，會根據呼叫中指定的時間傳回回應，指出地點目前是否營業。

這個方法會採用 GMSPlaceIsOpenWithRequest 類型的單一引數，其中包含：

  • GMSPlace 物件，或指定地點 ID 的字串。如要進一步瞭解如何使用必要欄位建立 Place 物件，請參閱「地點詳細資料」。
  • 選用的 NSDate (Obj-C) 或 Date (Swift) 物件，用於指定要檢查的時間。如未指定時間，則預設為現在。
  • 用來處理回應的 GMSPlaceOpenStatusResponseCallback 方法。
    • >

GMSPlaceIsOpenWithRequest 方法需要在 GMSPlace 物件中設定下列欄位：

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

如果 Place 物件中未提供這些欄位，或是您傳遞地點 ID，這個方法會使用 GMSPlacesClient GMSFetchPlaceRequest: 擷取這些欄位。

isOpenWithRequest 則回應

isOpenWithRequest 會傳回 GMSPlaceIsOpenResponse 物件，其中包含名為 status 的布林值，指出商家是營業中、已關閉，還是狀態不明。

語言 開啟時的值 關閉時的值 狀態不明時的值
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

「isOpenWithRequest」的帳單

  • GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位會依基本資料 SKU 收費。其餘營業時間則會依地點詳細資料企業 SKU 計費。
  • 如果您的 GMSPlace 物件已透過先前的要求取得這些欄位，系統不會再次收費。

範例：提出 GMSPlaceIsOpenWithRequest 要求

以下範例說明如何在現有的 GMSPlace 物件中初始化 GMSPlaceIsOpenWithRequest。

Places Swift SDK

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

必要參數

使用 GMSPlaceSearchNearbyRequest 物件指定搜尋的必要參數。

  • 欄位清單

    要求地點詳細資料時，您必須在地點的 GMSPlace 物件中，以欄位遮罩的形式指定要傳回的資料。如要定義欄位遮罩，請將值陣列從 GMSPlaceProperty 傳遞至 GMSPlaceSearchNearbyRequest 物件。欄位遮罩是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

    指定下列一或多個欄位：

    • 下列欄位會觸發 Nearby Search Pro SKU：

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyName
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlaceID
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

    • 下列欄位會觸發 Nearby Search Enterprise SKU：

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • 下列欄位會觸發Nearby Search Enterprise Plus SKU：

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

    以下範例會傳遞兩個欄位值的清單，指定要求傳回的 GMSPlace 物件包含 name 和 placeID 欄位：

    Places Swift SDK

    // 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

    GMSPlaceLocationRestriction 物件，用於定義要搜尋的區域 (以圓形表示)，並以中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設半徑為 0.0。您必須在要求中將這個值設為大於 0.0。

選用參數

使用 GMSPlaceSearchNearbyRequest 物件指定搜尋的選用參數。

  • includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

    可讓您指定類型清單 (來自類型 表 A)，用於篩選搜尋結果。每個類型限制類別最多可指定 50 個類型。

    地點只能有一個主要類型，且該類型必須與表 A 中的類型相關聯。舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。使用 includedPrimaryTypes 和 excludedPrimaryTypes 依地點的主要類型篩選結果。

    地點也可以有多個類型值，這些值來自與地點相關聯的表 A 類型。舉例來說，餐廳可能具有下列類型： "seafood_restaurant"、"restaurant"、"food"、 "point_of_interest"、"establishment"。使用 includedTypes 和 excludedTypes 篩選與地點相關聯的類型清單結果。

    指定一般主要類型 (例如 "restaurant" 或 "hotel") 時，回應可能包含主要類型比指定類型更具體的地點。舉例來說，您指定要納入 "restaurant" 的主要類型。因此，回應可能包含主要類型為 "restaurant" 的地點，但也可能包含主要類型更具體的地點，例如 "chinese_restaurant" 或 "seafood_restaurant"。

    如果搜尋條件指定多項類型限制，系統只會傳回符合所有限制的地點。舉例來說，如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}，系統傳回的地點會提供 "restaurant" 相關服務，但主要業務並非 "steak_house"。

    includedTypes

    要搜尋的地點類型清單，請參閱表 A。 如果省略這個參數，系統會傳回所有類型的地點。

    excludedTypes

    要從搜尋中排除的地點類型清單，請參閱表 A。

    如果在要求中同時指定 includedTypes (例如 "school") 和 excludedTypes (例如 "primary_school")，則回應會包含歸類為 "school" 但不屬於 "primary_school" 的地點。回應會包含符合至少一個 includedTypes 條件，且不符合任何 excludedTypes 條件的地點。

    如有任何衝突的型別 (例如同時出現在 includedTypes 和 excludedTypes 中的型別)，系統會傳回 INVALID_REQUEST 錯誤。

    includedPrimaryTypes

    要納入搜尋範圍的主要地點類型清單，請參閱表 A。

    excludedPrimaryTypes

    要從搜尋中排除的主要地點類型清單，請參閱表 A。

    如有任何衝突的主要類型 (例如同時出現在 includedPrimaryTypes 和 excludedPrimaryTypes 中的類型)，系統會傳回 INVALID_ARGUMENT 錯誤。

  • maxResultCount

    指定要傳回的地點結果數上限。必須介於 1 到 20 之間 (含 1 和 20)，預設為 20。

  • rankPreference

    要使用的排名類型。如果省略這個參數，系統會依熱門程度排序結果。 可能是下列其中一項：

    • .popularity (預設)：根據熱門程度排序結果。
    • .distance：依照地點與指定位置之間的距離，以遞增順序排列結果。

  • regionCode

    用於格式化回應的區域代碼，指定為 雙字元 CLDR 代碼值。沒有預設值。

    如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCode 相符，則 formattedAddress 會省略國家/地區代碼。這個參數不會影響 adrFormatAddress (一律會包含國家/地區名稱) 或 shortFormattedAddress (一律不會包含國家/地區名稱)。

    大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(對應到 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。視適用法律而定，這項參數可能會影響結果。

在應用程式中顯示出處資訊

如果應用程式會顯示以 GMSPlacesClient 取得的資訊 (例如相片和評論)，則也須顯示必要的出處資訊。

舉例來說，GMSPlacesClient 物件的 reviews 屬性最多可包含五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件都可以包含出處和作者出處。如果應用程式會顯示評論，則也須顯示任何出處或作者出處資訊。

詳情請參閱出處資訊說明文件。