搜尋附近地點 (新)

搜尋附近地點 (新版) 要求會接收要搜尋的區域 指定為圓形，格式為 圓形和半徑 (以公尺為單位)。這項要求會傳回相符地點清單，每個地點都以 GMSPlace敬上 物件，

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

Nearby Search (新版) 要求

透過呼叫提出 Nearby Search 要求 GMSPlacesClient searchNearbyWithRequest:、 傳送 GMSPlaceSearchNearbyRequest 物件，作用是定義要求參數以及回呼方法，類型為 GMSPlaceSearchNearbyResultCallback、 處理回應。

GMSPlaceSearchNearbyRequest 物件會指定 必填和選填屬性 參數。必要參數包括：

• 要在 GMSPlace 物件中傳回的欄位清單 (也稱為 欄位遮罩，如 GMSPlaceProperty。 如果您未在欄位清單中指定至少一個欄位，或 欄位清單，則呼叫會傳回錯誤。
• 位置限制，代表用於定義搜尋區域的圓形。

這個鄰近的搜尋要求範例會指定回應 GMSPlace 物件 包含地點名稱 (GMSPlacePropertyName) 和地點座標 針對搜尋中的每個 GMSPlace 物件 (GMSPlacePropertyCoordinate) 也就是預測結果也會篩選回應，只傳回「餐廳」類型的地點和「cafe」

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

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

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
}

Nearby Search 的回應

取得營業狀態

GMSPlacesClient 物件包含 isOpenWithRequest (Swiftt 中的 isOpenRequest，以及 GooglePlacesSwift 中的 isPlaceOpenRequest) 成員函式，可根據呼叫中指定的時間傳回回應，指出該地點目前是否營業。

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

• GMSPlace 物件，或是指定地點 ID 的字串。如要進一步瞭解如何運用必填欄位建立 Place 物件，請參閱「Place Details」。
  
• 選用的 NSDate (Obj-C) 或 Date (Swift) 物件，用於指定要查看的時間。如果您未指定時間，系統會採用預設值。
• 處理回應的 GMSPlaceOpenStatusResponseCallback 方法。
>

使用 GMSPlaceIsOpenWithRequest 方法時，您必須在 GMSPlace 物件中設定下列欄位：

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest 則回應

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

「isOpenWithRequest」的帳單

• GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位是依據 Basic Data SKU 計費。其餘的「營業時間」則會計入 Place Details (進階) SKU 下方。
• 如果 GMSPlace 物件「已經」有先前要求中的這些欄位，系統不會再次收費。

範例：發出 GMSPlaceIsOpenWithRequest 要求

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

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

          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
          }
          

必要參數

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

• 欄位清單

  要求 Place Details 時，您必須指定要用於 傳回地點的 GMSPlace 物件，做為欄位遮罩。如要定義 欄位遮罩，並將 GMSPlaceProperty 至 GMSPlaceSearchNearbyRequest 物件 欄位遮蓋是不錯的設計做法，確保您不會要求不必要的資料。 以避免不必要的處理時間和帳單費用。

  指定下列一或多個欄位：

  • 下列欄位會觸發 Nearby Search (基本) SKU：

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

  • 下列欄位會觸發 Nearby Search (Advanced) SKU：

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel、 GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

  • 下列欄位會觸發 Nearby Search (Preferred) SKU：

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

  以下範例傳送 欄位值 ，指出要求傳回的 GMSPlace 物件包含 name 和 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];
          

  Places Swift SDK for iOS (預先發布版)

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

• locationRestriction

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

選用參數

請使用 GMSPlaceSearchNearbyRequest 物件，為以下項目指定選用參數： 。

• includeTypes/excludedTypes、includePrimaryTypes/excludedPrimaryTypes

  讓您從類型指定類型清單 表 A 用於篩選資料 搜尋結果每個類型限制類別最多可以指定 50 種類型。

  一個地點只能有單一主要類型類型 與表 A 相關聯的 基礎架構舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。使用 includedPrimaryTypes和excludedPrimaryTypes可篩選以下項目的結果 地點的主要類型

  一個地點也可以有類型及多個類型值 表 A 相關聯的資源例如，餐廳可能會有下列類型： "seafood_restaurant"、"restaurant"、"food"、 "point_of_interest"、"establishment"。使用「includedTypes」 和 excludedTypes，篩選與指定類別相關聯的類型清單結果 特定地點。

  指定一般主要類型時，例如 "restaurant" 或 "hotel"，回應可以包含比主要類型更明確的地點 以及指定的 IP 位址舉例來說，您指定納入了主要類型 "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 (預設) 值，含首尾。

• 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敬上 如需儲存大量結構化物件 建議使用 Cloud Bigtable每個 GMSPlaceReview 物件都可以包含作者資訊以及作者作者資訊。 如果您在應用程式中顯示評論，則必須一併顯示作者資訊或作者。 出處。

詳情請參閱 作者資訊。