Text Search (新版)

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

Text Search 會根據字串傳回一組地點的相關資訊。例如「台南魯肉飯」、「西門町附近的鞋店」或「中正路 123 號」。這項服務會傳回與文字字串和任何位置自訂調整設定相符的地點清單。

這項服務特別適合在自動化系統中進行模糊地址查詢，且字串的非地址元件可能會與商家和地址相符。不清楚的地址查詢包括格式不正確的地址，或包含非地址元素 (例如商家名稱) 的要求。除非設定地點 (例如區域、地點限制或地點偏好設定)，否則前兩個範例中的要求可能會傳回零個結果。

「10 High Street, UK」或「123 Main Street, US」 英國有許多「High Street」；美國有許多「Main Street」。 除非設定位置限制，否則查詢不會傳回理想結果。
「連鎖餐廳 New York」 紐約有多個「連鎖餐廳」地點，但沒有街道地址或街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 英國城市埃舍 (Escher) 只有一個「High Street」；美國加州普萊森頓 (Pleasanton) 只有一個「Main Street」。
「UniqueRestaurantName New York」 紐約只有一家名稱相同的機構，因此不需要提供街道地址來區分。
「紐約市的披薩餐廳」 這個查詢包含位置限制，且「披薩餐廳」是明確定義的地點類型。會傳回多個結果。
「+1 514-670-8700」

這個查詢包含電話號碼。這個 API 會傳回與該電話號碼相關聯的地點多筆結果。

透過文字搜尋取得地點清單

呼叫 GMSPlacesClient searchByTextWithRequest: 來提出文字搜尋要求，並傳遞定義要求參數的 GMSPlaceSearchByTextRequest 物件，以及 GMSPlaceSearchByTextResultCallback 類型的回呼方法，以便處理回應。

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

  • 在 GMSPlace 物件中傳回的欄位清單，也稱為 欄位遮罩，由 GMSPlaceProperty 定義。如果您未在欄位清單中指定至少一個欄位，或是省略欄位清單，則呼叫會傳回錯誤。
  • 文字查詢。

這個文字搜尋要求範例會指定回應 GMSPlace 物件包含搜尋結果中每個 GMSPlace 物件的地點名稱和地點 ID。並篩選回應，只傳回「餐廳」類型的地點。

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [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().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

iOS 版 Places Swift SDK (預覽版)

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

文字搜尋回覆

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

取得開放狀態

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

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

  • GMSPlace 物件，或指定地點 ID 的字串。如要進一步瞭解如何建立含有必要欄位的 Place 物件，請參閱「Place 詳細資料」。
  • 選用的 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 (進階)」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
          }

必要參數

使用 GMSPlaceSearchByTextRequest 物件指定搜尋作業的必要參數。

  • 欄位清單

    指定要傳回的地點資料屬性。傳遞 GMSPlace 屬性清單，指定要傳回的資料欄位。如果省略欄位遮罩，要求就會傳回錯誤。

    欄位清單是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

    指定下列一或多個欄位：

    • 以下欄位會觸發 Text Search (ID Only) SKU：

      GMSPlacePropertyPlaceID， GMSPlacePropertyName

    • 以下欄位會觸發 Text Search (Basic) SKU：

      GMSPlacePropertyAddressComponents、GMSPlacePropertyBusinessStatus、GMSPlacePropertyFormattedAddress、GMSPlacePropertyIconBackgroundColor、GMSPlacePropertyIconImageURL、GMSPlacePropertyCoordinate、GMSPlacePropertyPhotos、GMSPlacePropertyPlusCode、GMSPlacePropertyTypes、GMSPlacePropertyUTCOffsetMinutes、GMSPlacePropertyViewport、GMSPlacePropertyWheelchairAccessibleEntrance

    • 以下欄位會觸發 Text Search (Advanced) SKU：

      GMSPlacePropertyCurrentOpeningHours、GMSPlacePropertySecondaryOpeningHours、GMSPlacePropertyPhoneNumber、GMSPlacePropertyPriceLevel、GMSPlacePropertyRating、GMSPlacePropertyOpeningHours、GMSPlacePropertyUserRatingsTotal、GMSPlacePropertyWebsite

    • 以下欄位會觸發 Text Search (Preferred) SKU：

      GMSPlacePropertyCurbsidePickup、GMSPlacePropertyDelivery、GMSPlacePropertyDineIn、GMSPlacePropertyEditorialSummary、GMSPlacePropertyReservable、GMSPlacePropertyReviews、GMSPlacePropertyServesBeer、GMSPlacePropertyServesBreakfast、GMSPlacePropertyServesBrunch、GMSPlacePropertyServesDinner、GMSPlacePropertyServesLunch、GMSPlacePropertyServesVegetarianFood、GMSPlacePropertyServesWine、GMSPlacePropertyTakeout

  • textQuery

    要搜尋的文字字串，例如「餐廳」、「中正路 123 號」或「舊金山最佳景點」。

選用參數

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

  • includedType

    將結果限制在符合 表 A 所定義的指定類型。只能指定一種類型。例如：

    • request.includedType = "bar"
    • request.includedType = "pharmacy"

  • isOpenNow

    如果為 true，則只會傳回在查詢當下營業中的地點。如果為 false，則無論營業狀態為何，都會傳回所有商家。如果您將這個參數設為 false，系統就會傳回未在 Google 地點介面集資料庫中指定營業時間的地點。

  • isStrictTypeFiltering

    與 includeType 參數搭配使用。設為 true 時，系統只會傳回符合 includeType 指定的指定類型地點。如果為 false (預設值)，回應可能包含不符合指定類型的地點。

  • locationBias

    指定要搜尋的區域。這個位置會做為偏差值，也就是說，系統可以傳回指定位置附近的結果，包括指定區域外的結果。

    您可以指定 locationRestriction 或 locationBias，但不能兩者同時指定。請將 locationRestriction 視為指定結果必須位於其中的區域，而 locationBias 視為指定結果必須位於附近，但可位於區域外的區域。

    將區域指定為矩形可視區域或圓形。

    • 圓形的定義是中心點和半徑 (以公尺為單位)。半徑必須介於 0.0 和 50000.0 之間 (含首尾)。預設半徑為 0.0。例如：

      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

    • 矩形是經緯度可視區域，以兩個對角相反的低點和高點表示。低點代表矩形的西南角，高點則代表矩形的東北角。

      可視區域視為封閉區域，也就是包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 度之間 (含首尾)：

      • 如果 low = high，可視區域就會包含該單一點。
      • 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域會跨越 180 度經線)。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度，則可視區域會包含所有經度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會是空白。
      • 如果 low.latitude > high.latitude，則經度範圍為空白。

  • locationRestriction

    指定要搜尋的區域。系統不會傳回指定區域以外的結果。將區域指定為矩形可視區域。如要進一步瞭解如何定義可視區域，請參閱 locationBias 的說明。

    您可以指定 locationRestriction 或 locationBias，但不能兩者同時指定。請將 locationRestriction 視為指定結果必須位於其中的區域，而 locationBias 視為指定結果必須位於附近，但可位於區域外的區域。

  • maxResultCount

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

  • minRating

    只列出平均使用者評分大於或等於此限制的房源。值必須介於 0.0 和 5.0 (含) 之間，以 0.5 為單位遞增。例如：0、0.5、1.0、...、5.0 (含)。值會進位至最接近的 0.5。舉例來說，如果值為 0.6，系統就會排除所有評分低於 1.0 的結果。

  • priceLevels

    將搜尋範圍限制在特定價格範圍內的地點。預設會選取所有價格等級。

    指定由 PriceLevel 定義的一或多個值的陣列。

    例如：

    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    根據查詢類型指定結果在回應中排序的方式：

    • 如果是分類查詢 (例如「紐約市的餐廳」)，預設會使用 .relevance (依搜尋關聯性排序結果)。您可以將 rankPreference 設為 .relevance 或 .distance (依距離排序結果)。
    • 如果是「Mountain View, CA」等非分類查詢，建議您不要設定 rankPreference。

  • regionCode

    用於格式化回應的區碼，指定為 兩個字元的 CLDR 代碼值。這個參數也會對搜尋結果產生偏差效果。沒有預設值。

    如果回應中的地址欄位國家/地區名稱與區域代碼相符，系統就會從地址中省略國家/地區代碼。

    大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。這個參數可能會影響根據適用法律產生的結果。

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

如果應用程式會顯示從 GMSPlacesClient 取得的資訊 (例如相片和評論)，則也必須顯示必要的出處資訊。

舉例來說，GMSPlacesClient 物件的 reviews 屬性包含最多五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件都可以包含歸屬資訊和作者歸屬資訊。如果您在應用程式中顯示評論，則必須一併顯示任何出處資訊或作者出處資訊。

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