Text Search (新版)

您必須啟用新一代的 Places API，才能使用這項功能。詳情請參閱「啟用 API」相關說明。

Text Search 可根據字串傳回一組地點的相關資訊。例如「臺北披薩」、「渥太華附近的鞋店」或「中正路 123 號」。這項服務會傳回與文字字串和任何位置自訂調整設定相符的地點清單。

此服務特別適合在自動化系統中建立模糊的位址查詢，且字串的非地址元件可能會與商家或地址進行比對。模稜兩可的地址查詢範例包括地址格式不正確，或包含非地址元件 (例如商家名稱) 的要求。除非已設定位置 (例如區域、位置限製或位置自訂調整)，否則如前兩個範例的要求可能會傳回零結果。

「10 High Street, UK」或「123 Main Street, US」	英國有多個「高街」，美國境內還有多條「主要街道」。 除非已設定位置限制，否則查詢不會傳回符合需求的結果。
「紐約連鎖餐廳」	在紐約設有多個「連鎖餐廳」地點；沒有街道地址，甚至是街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」	英國 Escher 城市中只有一號「高街」，在美國普萊森頓市只有一道「主要街道」。
「Unique 餐廳 Name 紐約」	在紐約只使用一間名稱的建築物，不需要區分街道地址。
「臺北披薩餐廳」	這項查詢包含地點限制，而「披薩餐廳」是定義明確的地點類型。這個方法會傳回多個結果。
「[phone]」	這項查詢包含電話號碼。針對與該電話號碼相關聯的地點，傳回多筆結果。 注意： 為確保透過電話號碼搜尋時能獲得最佳結果，請加入國家/地區代碼，並在後方加上空格，並將 regionCode 參數設為與國家/地區代碼對應。

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

呼叫 GMSPlacesClient searchByTextWithRequest: 並傳遞用於定義要求參數和回呼方法 (類型為 GMSPlaceSearchByTextResultCallback) 的 GMSPlaceSearchByTextRequest 物件，即可發出 Text Search 要求來處理回應。

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

GooglePlacesSwift

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 回應

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

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

除了資料欄位，回應中的 GMSPlace 物件還包含下列成員函式：

• isOpen 會計算地點在特定時間是否營業中。
• isOpenAtDate 會計算地點在特定日期是否營業。

注意：只有在啟用 Places SDK for iOS 後，才能使用這些函式。啟用 Places SDK for iOS (新版) 時無法使用這些功能。詳情請參閱「選擇 SDK 版本」。

必要參數

請使用 GMSPlaceSearchByTextRequest 物件指定搜尋所需的參數。

• 欄位清單

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

  欄位清單是不錯的設計做法，可避免要求不必要的資料，避免不必要的處理時間和帳單費用。

  請指定下列一或多個欄位：

  • 下列欄位會觸發文字搜尋 (僅限 ID) 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"
  注意： 表格 B 中的值只會在回應中傳回。您無法使用資料表 B 中的值做為篩選條件。

• isOpenNow

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

• isStrictTypeFiltering

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

• locationBias

  指定要搜尋的區域。這個位置可以做為自訂調整，這表示系統會傳回指定位置周圍的結果，包括指定區域以外的結果。

  您可以指定 locationRestriction 或 locationBias，但不能同時指定兩者。您可以將 locationRestriction 視為指定結果所在的區域，而 locationBias 是用於指定結果的鄰近區域，但可以不在該區域。

  注意： 如果您同時省略 locationBias 和 locationRestriction，根據預設，API 會使用 IP 自訂調整。透過 IP 自訂調整，API 會使用裝置的 IP 位址來自訂結果。
  注意： 如果 textQuery 包含 Market in Barcelona 等明確位置，則可覆寫 locationBias 參數。在這種情況下，系統會忽略 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 是用於指定結果的鄰近區域，但可以不在該區域。

  注意： 如果您同時省略 locationBias 和 locationRestriction，根據預設，API 會使用 IP 自訂調整。透過 IP 自訂調整，API 會使用裝置的 IP 位址來調整結果。

• 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 定義的一或多個值的陣列。

  注意： 要求中不允許使用 PRICE_LEVEL_FREE。只會用於填入回應。

  例如：

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

• rankPreference

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

  • 如果是如「紐約市餐廳」等類別查詢，系統會預設 .relevance (依搜尋關聯性排名結果)。 您可以將 rankPreference 設為 .relevance 或 .distance (依距離排名結果)。
  • 如果是非類別查詢 (例如「加州山景城」)，建議您不要設定 rankPreference。

• regionCode

  用於設定回應格式的區碼，指定為 雙字元 CLDR 代碼值。此外，這項參數也會對搜尋結果產生偏誤。沒有預設值。

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

  大多數 CLDR 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律，這個參數可能會影響結果。

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

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

例如，GMSPlacesClient 物件的 reviews 屬性包含最多五個 GMSPlaceReview 物件的陣列。每個 GMSPlaceReview 物件皆可包含作者資訊和作者作者資訊。如果您在應用程式中顯示評論，則您也必須顯示所有作者資訊或作者作者資訊。

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