Nearby Search (新版)

選取平台： Android iOS JavaScript 網頁服務

您必須啟用新一代的 Places API，才能使用這項功能。詳情請參閱「啟用 API」。

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

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

Nearby Search (新版) 要求

呼叫 GMSPlacesClient searchNearbyWithRequest: 即可提出附近搜尋要求，並傳遞定義要求參數的 GMSPlaceSearchNearbyRequest 物件，以及 GMSPlaceSearchNearbyResultCallback 類型的回呼方法，以便處理回應。

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

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

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

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

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

Nearby Search 回應

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

注意： 回應 GMSPlace 物件的欄位不得為空白。舉例來說，如果欄位清單包含 GMSPlacePropertyPhotos 以便要求回應中的 photos 欄位，而回應中的 photos 欄位為空白，則會從回應 GMSPlace 物件中省略。

取得開放狀態

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

注意：已淘汰的 GMSPlace isOpen: 和 GMSPlace isOpenAtDate: 函式可能不準確，不建議與 Places API (新版) 搭配使用。

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

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

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

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest 則回應

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

語言	如果已開啟，則為值	關閉時的值	狀態不明時的值
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown
GooglePlacesSwift (預先發布版)	true	false	nil

「isOpenWithRequest」的帳單

• 系統會針對 GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位收取 Basic Data SKU 費用。系統會根據 Place Details Enterprise SKU收取其他營業時間的費用。
• 如果 GMSPlace 物件已包含先前要求中的這些欄位，就不會再向您收費。
• 警告：如果 GMSPlace 物件沒有這些欄位，系統會再次收取Basic Data SKU 費用。系統會根據 Place Details Enterprise SKU 收取其他營業時間的費用。如果您的專案會使用 isOpenWithRequest，建議您務必擷取必要的地點詳細資料。

範例：提出 GMSPlaceIsOpenWithRequest 要求

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

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

GooglePlacesSwift

          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 物件指定搜尋作業的必要參數。

• 欄位清單

  要求地點詳細資料時，您必須在 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 欄位：

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

  iOS 版 Places Swift SDK (預覽版)

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

• locationRestriction

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

選用參數

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

• includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

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

  注意： 表格 B 中的值只會在回應中傳回。您無法使用 Table B 中的值做為篩選器。

  地點只能有 單一主要類型，且該類型必須與 表格 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、excludedTypes、includedPrimaryTypes 和 excludedPrimaryTypes，搜尋結果會傳回位置限制範圍內的所有類型地點。

  includedTypes

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

  excludedTypes

  表 A 中要排除的場所類型清單。

  如果您在要求中同時指定 includedTypes (例如 "school") 和 excludedTypes (例如 "primary_school")，回應就會包含歸類為 "school" 但非 "primary_school" 的 Places。回應會包含與 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 物件的陣列。每個 GMSPlaceReview 物件都包含歸屬資訊和作者歸屬資訊。如果您在應用程式中顯示評論，則必須一併顯示任何出處資訊或作者出處資訊。

詳情請參閱歸因說明文件。