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

Text Search (新版)

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

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

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

「英國 10 號」或「美國中正路 123 號」	英國的多個「高街」；美國的多個「中正路」。如未設定位置限制，查詢就不會傳回理想的結果。
「臺北市中餐廳」	紐約有多個「中菜餐廳」地點，沒有街道地址或街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」	英國埃塞爾 (Escher) 的英國城市「高街」；在加州普萊桑頓市內只有一個「Main Street」(主街)。
「UniqueRestaurantName New York」	紐約只能有一間名稱的建築物，不需要街道地址即可區分。
「臺北市的披薩店」	這項查詢包含地點限制，而「披薩餐廳」是定義明確的地點類型。並傳回多項結果。
「+1 514-670-8700」	這項查詢包含電話號碼。並傳回多個與該電話號碼相關聯的地點結果。注意：為了在電話號碼搜尋時獲得最佳結果，請加入國家/地區代碼，並在後方加上空格，然後將 `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 會計算地點在指定日期是否營業。

必要參數

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

欄位清單

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

欄位清單很適合用來確保您不會要求不必要的資料，這有助於避免不必要的處理時間和帳單費用。

指定下列一或多個欄位：
- 下列欄位會觸發 Text Search (ID Only) SKU：
  GMSPlacePropertyPlaceID、GMSPlacePropertyName
- 下列欄位會觸發 Text Search (基本) SKU：
  GMSPlacePropertyAddressComponents、 GMSPlacePropertyBusinessStatus、 GMSPlacePropertyFormattedAddress、 GMSPlacePropertyIconBackgroundColor、 GMSPlacePropertyIconImageURL、 GMSPlacePropertyCoordinate、 GMSPlacePropertyPhotos、 GMSPlacePropertyPlusCode、 GMSPlacePropertyTypes、 GMSPlacePropertyUTCOffsetMinutes、 GMSPlacePropertyViewport、 GMSPlacePropertyWheelchairAccessibleEntrance
- 下列欄位會觸發 Text Search (進階) 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 (預設) 之間 (含 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 (按照距離排名結果)。
- 如果是非類別查詢，例如「Mountain View, CA」，建議不設定 rankPreference。
regionCode

用於設定回應格式的區碼，以雙字元 CLDR 代碼值指定。這個參數也可能會對搜尋結果造成偏誤。沒有預設值。

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

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

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

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

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

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