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

搜尋附近地點 (新)

「搜尋附近」(New) 要求會採用以圓形形式指定搜尋區域，由圓形中心點的經緯度座標及半徑 (以公尺為單位) 定義。該要求會在指定搜尋區域中傳回相符地點的清單，每個地點以 GMSPlace 物件表示。

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

Nearby Search (新) 要求

呼叫 GMSPlacesClient searchNearbyWithRequest: 並傳遞用於定義要求參數和回呼方法 (類型為 GMSPlaceSearchNearbyResultCallback) 的 GMSPlaceSearchNearbyRequest 物件，即可提出 Nearby Search 要求來處理回應。

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

要在 GMSPlace 物件中傳回的欄位清單，該欄位也稱為「欄位遮罩」，定義由 GMSPlaceProperty 定義。如果您未在欄位清單中指定至少一個欄位，或是省略欄位清單，呼叫會傳回錯誤。
地區限制：代表搜尋區域的圓形範圍。

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

Swift

// Array to hold the places in the response
placeResults = [];

// 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
  }
  self.placeResults = results
}

GMSPlacesClient.shared().searchNearbyWithRequest(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) {
      [weakSelf showErrorWithMessage:error.localizedDescription];
    } 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 (Basic) 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 物件指定搜尋的選用參數。

includeType/excludedTypes、includePrimaryTypes/excludedPrimaryType

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

注意： 表格 B 中的值只會在回應中傳回。您無法使用資料表 B 中的值做為篩選條件。
地點只能擁有相關聯表 A 類型的單一主要類型。舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。使用 includedPrimaryTypes 和 excludedPrimaryTypes 即可依據地點的主要類型篩選結果。

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

如果指定搜尋時設有多種類型限制，系統只會傳回符合所有限制的地點。舉例來說，如果您指定 {"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 物件的陣列。每個 GMSPlaceReview 物件皆可包含作者資訊和作者作者資訊。如果您在應用程式中顯示評論，則您也必須顯示所有作者資訊或作者作者資訊。

如需更多資訊，請參閱歸因說明文件。

搜尋附近地點 (新)

Nearby Search (新) 要求

Swift

Objective-C

GooglePlacesSwift

Nearby Search 回應

必要參數

欄位清單

Swift

Objective-C

GooglePlacesSwift

locationRestriction

自選參數

includeType/excludedTypes、includePrimaryTypes/excludedPrimaryType

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

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