搜尋附近地點 (新)

搜尋附近地點 (新版) 要求會接收要搜尋的區域 指定為圓形,格式為 圓形和半徑 (以公尺為單位)。這項要求會傳回相符地點清單,每個地點都以 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;
    }
  }
];

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

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

取得營業狀態

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 的布林值,以指出商家是否為營業中、已停業或狀態不明。

語言 值開啟時的價值 關閉後的價值 狀態不明時傳回的值
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (預先發布版) true false nil

isOpenWithRequest」的帳單

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

範例:發出 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 物件指定必要的參數 。

  • 欄位清單

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

    指定下列一或多個欄位:

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

      GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyCoordinate, GMSPlacePropertyFormattedAddressGMSPlacePropertyName, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyPhotos, GMSPlacePropertyPlaceID, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, GMSPlacePropertyWheelchairAccessibleEntrance

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

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevelGMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

      GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummaryGMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

    以下範例傳送 欄位值 ,指出要求傳回的 GMSPlace 物件包含 nameplaceID 欄位:

    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"。使用 includedPrimaryTypesexcludedPrimaryTypes可篩選以下項目的結果 地點的主要類型

    一個地點也可以有類型及多個類型值 表 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 特定內容

    如果主要類型有相衝突的主要類型, includedPrimaryTypesexcludedPrimaryTypes, 傳回 INVALID_ARGUMENT 錯誤。

  • maxResultCount

    指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 值,含首尾。

  • rankPreference

    要使用的排名類型。如果省略這個參數,結果會按照熱門程度排名。 可以是下列其中一項:

    • .popularity (預設) 依據熱門程度將結果排序。
    • .distance 依地點與 指定位置。
  • regionCode

    用於設定回應格式的區碼,以 也就是雙字元 CLDR 代碼值。沒有預設值。

    如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCodeformattedAddress 中省略了國家/地區代碼。 這個參數不會影響 adrFormatAddress,一律包含國家/地區 名稱或 shortFormattedAddress 上 (絕不會包含此項目)。

    大多數 CLDR 代碼 ISO 3166-1 代碼 有一些值得注意的例外情況舉例來說,英國的 ccTLD 是 「uk」(.co.uk),但 ISO 3166-1 代碼卻是「gb」(技術上來說 「大不列顛暨北愛爾蘭聯合王國」)。 這個參數會根據適用法律影響結果。

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

應用程式顯示 GMSPlacesClient、 (例如相片和評論),應用程式也必須顯示必要的作者資訊。

例如 GMSPlacesClient 物件的 reviews 屬性 包含一個最多五個的陣列 GMSPlaceReview敬上 如需儲存大量結構化物件 建議使用 Cloud Bigtable每個 GMSPlaceReview 物件都可以包含作者資訊以及作者作者資訊。 如果您在應用程式中顯示評論,則必須一併顯示作者資訊或作者。 出處。

詳情請參閱 作者資訊