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

Text Search (新版)

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

歐洲經濟區 (EEA) 開發人員

Text Search (新版) 會根據字串 (例如「紐約市的披薩」、「渥太華附近的鞋店」或「中正路 123 號」)，傳回一組地點的相關資訊。這項服務會傳回與文字字串及位置自訂調整設定相符的地點清單。

除了必要參數，Text Search (新版) 也支援使用選用參數來精確查詢，以獲得更理想的結果。

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

呼叫 GMSPlacesClient searchByTextWithRequest:，並傳遞 GMSPlaceSearchByTextRequest 物件 (定義要求參數) 和 GMSPlaceSearchByTextResultCallback 類型的回呼方法，即可提出「文字搜尋」要求，以處理回應。

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

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

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

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      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
}

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

Text Search 回應

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

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

取得營業狀態

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

注意：已淘汰的 GMSPlace isOpen: 和 GMSPlace isOpenAtDate: 函式可能不準確，不適合與 Places API (新版) 搭配使用。

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

GMSPlace 物件，或指定地點 ID 的字串。如要進一步瞭解如何使用必要欄位建立 Place 物件，請參閱「地點詳細資料」。

注意：Place 物件必須包含有效的地點 ID。
選用的 NSDate (Obj-C) 或 Date (Swift) 物件，用於指定要檢查的時間。如未指定時間，則預設為現在。
用來處理回應的 GMSPlaceOpenStatusResponseCallback 方法。

GMSPlaceIsOpenWithRequest 方法需要在 GMSPlace 物件中設定下列欄位：

GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours

如果 Place 物件中未提供這些欄位，或是您傳遞地點 ID，這個方法會使用 GMSPlacesClient GMSFetchPlaceRequest: 擷取這些欄位。

`isOpenWithRequest` 則回應

isOpenWithRequest 會傳回 GMSPlaceIsOpenResponse 物件，其中包含名為 status 的布林值，指出商家是營業中、已關閉，還是狀態不明。

語言	開啟時的值	關閉時的值	狀態不明時的值
Places Swift	`true`	`false`	`nil`
Swift	`.open`	`.closed`	`.unknown`
Objective-C	`GMSPlaceOpenStatusOpen`	`GMSPlaceOpenStatusClosed`	`GMSPlaceOpenStatusUnknown`

「`isOpenWithRequest`」的帳單

GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 欄位會依基本資料 SKU 收費。其餘營業時間則會依地點詳細資料企業 SKU 計費。
如果您的 GMSPlace 物件已透過先前的要求取得這些欄位，系統不會再次收費。
警告：如果 GMSPlace 物件沒有這些欄位，系統會再次針對 Basic Data SKU 收費。其餘營業時間則會以地點詳細資料企業 SKU 計費。如果專案會使用 isOpenWithRequest，建議您務必擷取必要地點詳細資料。

範例：提出 `GMSPlaceIsOpenWithRequest` 要求

以下範例說明如何在現有的 GMSPlace 物件中初始化 GMSPlaceIsOpenWithRequest。

Places Swift SDK

        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
        }

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

必要參數

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

欄位清單

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

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

指定下列一或多個欄位：
- 以下欄位會觸發 Text Search Essentials ID Only SKU：
  GMSPlacePropertyPlaceID
- 下列欄位會觸發 Text Search Pro SKU：
  GMSPlacePropertyAddressComponents
  GMSPlacePropertyBusinessStatus
  GMSPlacePropertyCoordinate
  GMSPlacePropertyFormattedAddress
  GMSPlacePropertyIconBackgroundColor
  GMSPlacePropertyIconImageURL
  GMSPlacePropertyName
  GMSPlacePropertyPhotos
  GMSPlacePropertyPlusCode
  GMSPlacePropertyTypes
  GMSPlacePropertyUTCOffsetMinutes
  GMSPlacePropertyViewport
  GMSPlacePropertyWheelchairAccessibleEntrance
- 下列欄位會觸發 Text Search Enterprise SKU：
  GMSPlacePropertyCurrentOpeningHours
  GMSPlacePropertySecondaryOpeningHours
  GMSPlacePropertyPhoneNumber
  GMSPlacePropertyPriceLevel
  GMSPlacePropertyRating
  GMSPlacePropertyOpeningHours
  GMSPlacePropertyUserRatingsTotal
  GMSPlacePropertyWebsite
- 下列欄位會觸發 Text Search Enterprise Plus SKU：
  GMSPlacePropertyCurbsidePickup
  GMSPlacePropertyDelivery
  GMSPlacePropertyDineIn
  GMSPlacePropertyEditorialSummary
  GMSPlacePropertyReservable
  GMSPlacePropertyReviews
  GMSPlacePropertyServesBeer
  GMSPlacePropertyServesBreakfast
  GMSPlacePropertyServesBrunch
  GMSPlacePropertyServesDinner
  GMSPlacePropertyServesLunch
  GMSPlacePropertyServesVegetarianFood
  GMSPlacePropertyServesWine
  GMSPlacePropertyTakeout
textQuery

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

注意： 如要獲得最佳電話號碼搜尋結果，請加入國家/地區代碼，並在後面加上空格，然後將 regionCode 參數設為對應的國家/地區代碼。電話號碼格式因國家/地區而異，API 會嘗試傳回這些不同格式的結果。

選用參數

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

includedType

讓系統在結果中只顯示符合表 A 所定義類型的地點。只能指定一個類型。例如：
- let request = SearchByTextRequest() request.includedType = "bar"
- let request = SearchByTextRequest() 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。例如：
```
let request = SearchByTextRequest()
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)，預設為 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。僅用於填入回覆內容。

例如：
```
    let request = SearchByTextRequest()
    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」(嚴格來說，這是「大不列顛及北愛爾蘭聯合王國」實體的代碼)。根據適用法律，這項參數可能會影響結果。

shouldIncludePureServiceAreaBusinesses

如果為 true，則會在搜尋結果中傳回純服務範圍商家。純區域服務商家會為顧客提供直接送貨或到府服務，但不在商家地址提供服務。

例如：

Places Swift SDK

let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

Swift

let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

Objective-C

GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

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

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

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

詳情請參閱出處資訊的說明文件。

Text Search (新版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

Places Swift SDK

Swift

Objective-C

Text Search 回應

取得營業狀態

isOpenWithRequest 則回應

「isOpenWithRequest」的帳單

範例：提出 GMSPlaceIsOpenWithRequest 要求

Places Swift SDK

Swift

Objective-C

必要參數

欄位清單

textQuery

選用參數

includedType

isOpenNow

isStrictTypeFiltering

locationBias

locationRestriction

maxResultCount

minRating

priceLevels

rankPreference

regionCode

shouldIncludePureServiceAreaBusinesses

Places Swift SDK

Swift

Objective-C

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

Text Search (新版)

`isOpenWithRequest` 則回應

「`isOpenWithRequest`」的帳單

範例：提出 `GMSPlaceIsOpenWithRequest` 要求