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

搜尋附近地點 (新)

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

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

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

Nearby Search (新版) 要求

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

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

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

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

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

GooglePlacesSwift

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 物件會省略此屬性。

除了資料欄位之外，GMSPlace 回應包含下列成員函式：

isOpen 會計算地點在指定時間是否營業。
isOpenAtDate敬上計算地點在指定日期是否營業。

，瞭解如何調查及移除這項存取權。

必要參數

請使用 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];
        
```
GooglePlacesSwift
```
// 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 種類型。

注意： 表 B 只會出現在回應中。您無法在以下位置使用值：按表 B 使用篩選器。

一個地點只能有單一主要類型類型與表 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、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 (預設) 值，含首尾。
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 物件都可以包含作者資訊以及作者作者資訊。如果您在應用程式中顯示評論，則必須一併顯示作者資訊或作者。出處。

詳情請參閱作者資訊。

搜尋附近地點 (新)

Nearby Search (新版) 要求

Swift

Objective-C

GooglePlacesSwift

Nearby Search 的回應

必要參數

欄位清單

Swift

Objective-C

GooglePlacesSwift

locationRestriction

選用參數

includeTypes/excludedTypes、includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

在應用程式中顯示作者資訊