本頁面由 Cloud Translation API 翻譯而成。

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 物件。

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

取得營業狀態

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

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

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

GMSPlace 物件，或指定地點 ID 的字串。如要進一步瞭解如何使用必要欄位建立 Place 物件，請參閱「地點詳細資料」。

注意：Place 物件必須包含有效的地點 ID。
選用的 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 物件已透過先前的要求取得這些欄位，系統不會再次收費。
警告：如果 GMSPlace 物件沒有這些欄位，系統會再次收取 Basic Data SKU 的費用。其餘營業時間則會以地點詳細資料企業 SKU 計費。如果專案會使用 isOpenWithRequest，建議您務必擷取必要地點詳細資料。

範例：提出 `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 個類型。

注意： 只有表格 B 中的值會傳回至回應。您無法使用表 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" 的地點。回應會包含符合至少一個 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 物件都可以包含出處和作者出處。如果應用程式會顯示評論，則也須顯示任何出處或作者出處資訊。

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

Nearby Search (新版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Nearby Search (新版) 要求

Places Swift SDK

Swift

Objective-C

Nearby Search 回應

取得營業狀態

isOpenWithRequest 則回應

「isOpenWithRequest」的帳單

範例：提出 GMSPlaceIsOpenWithRequest 要求

Places Swift SDK

Swift

Objective-C

必要參數

欄位清單

Places Swift SDK

Swift

Objective-C

locationRestriction

選用參數

includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

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

Nearby Search (新版)

`isOpenWithRequest` 則回應

「`isOpenWithRequest`」的帳單

範例：提出 `GMSPlaceIsOpenWithRequest` 要求