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

Text Search (新版)

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

Text Search 會傳回一組地點的相關資訊來產生這種文字說明的模型例如：「臺北披薩」、「附近的鞋店渥太華」或「中正路 123 號」。這項服務會傳回地點清單比對文字字串和任何已設定的位置自訂調整。

這項服務在建立語意明確的地址時特別實用查詢字串中的非地址元件可能與商家讓我們看看 DNS 解析進一步探索內部和外部位址不清楚的地址查詢範例包括格式不正確的地址，或是包含非地址元素 (例如商家名稱) 的要求。除非設定地點 (例如地區、地點限制或地點偏好設定)，否則前兩個範例中的要求可能會傳回零個結果。

「英國 10 號高街」或「美國中正路 123 號」	英國的多個「高街」；美國境內的多個「主街」。除非有地點限制，否則查詢不會傳回理想的結果設定。
「臺北市中餐廳」	多間「中國餐廳」臺北市無街道地址，甚至是街道名稱
「10 High Street, Escher UK」或「美國臺北市中正區 123 號」	只有一個「高街」；只有一個「中正路」美國境內 Pleasanton CA
「UniqueRestaurantName New York」	紐約地只有一間同名的建築物；無街道地址以便區分。
「紐約市的披薩餐廳」	這項查詢包含其位置限制和「披薩餐廳」為定義明確的地點類型並傳回多項結果。
「+1 514-670-8700」	這項查詢包含電話號碼。它會傳回多個以下項目的結果：與該組電話號碼相關聯的地點。注意：為了在搜尋時獲得最佳結果輸入國家/地區代碼，後面加上空格，且設定`regionCode` 參數值。

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

呼叫 GMSPlacesClient searchByTextWithRequest: 即可發出 Text Search 要求。傳送 GMSPlaceSearchByTextRequest 物件，作用是定義要求參數以及回呼方法，類型為 GMSPlaceSearchByTextResultCallback, 處理回應。

GMSPlaceSearchByTextRequest 物件會指定 required 和 optional 參數。必要參數包括：

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

Text Search API 會在形式 GMSPlace敬上物件，每個相符地點都有一個 GMSPlace 物件。

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

取得開放狀態

GMSPlacesClient 物件包含 isOpenWithRequest (Swiftt 中的 isOpenRequest，以及 GooglePlacesSwift 中的 isPlaceOpenRequest) 成員函式，可根據呼叫中指定的時間傳回回應，指出該地點目前是否營業。

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

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

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

注意：Place 物件必須包含有效的地點 ID。
選用的 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 物件「已經」有先前要求中的這些欄位，系統不會再次收費。
警告：如果您的 GMSPlace 物件沒有這些欄位，系統會再次向您收取基本資料 SKU 的費用。其餘的「營業時間」則會計入 Place Details (進階) SKU 下方。如果專案會使用 isOpenWithRequest，建議你確保擷取必要的地點詳細資料。

範例：發出 `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 (基本) 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，請退回所有商家不論是否開啟狀態在 Google 地點介面集資料庫中，未指定營業時間的地點，就是如果您將這個參數設為 false，就會傳回。
isStrictTypeFiltering

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

指定要搜尋的區域。這個位置只是偏見可以傳回指定位置附近的結果，包括結果指定區域外。

您可以指定 locationRestriction 或 locationBias 但不能同時採用兩者您可以將 locationRestriction 想成是指定結果所在的區域，以及 locationBias 為用於指定結果必須鄰近的區域，但可以位於這個區域

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

注意：如果 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 會使用以便調整結果。
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 (依距離排名結果)。
- 如果是非類別查詢，例如「Mountain View, CA」您未設定 rankPreference。
regionCode

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

如果回覆地址欄位的國家/地區名稱與區碼，則地址中略過國家/地區代碼。

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

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

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

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

詳情請參閱作者資訊。

Text Search (新版)

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

Swift

Objective-C

iOS 版 Places Swift SDK (預覽版)

Text Search 回應

取得開放狀態

isOpenWithRequest 則回應

「isOpenWithRequest」的帳單

範例：發出 GMSPlaceIsOpenWithRequest 要求

Swift

Objective-C

GooglePlacesSwift

必要參數

欄位清單

textQuery

選用參數

includedType

isOpenNow

isStrictTypeFiltering

locationBias

locationRestriction

maxResultCount

minRating

priceLevels

rankPreference

regionCode

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

`isOpenWithRequest` 則回應

「`isOpenWithRequest`」的帳單

範例：發出 `GMSPlaceIsOpenWithRequest` 要求