Text Search (新版)

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

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

如果您的帳單地址位於歐洲經濟區，自 2025 年 7 月 8 日起，使用服務時將適用《 Google 地圖平台歐洲經濟區服務條款》。功能會因區域而異。 瞭解詳情。

這項功能需要啟用新一代的 Places API，也就是 Places API (新版)。詳情請參閱啟用 API。

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

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

「10 High Street, UK」或「123 Main Street, US」	英國境內有多條「High Street」；美國境內有多條「Main Street」。 除非設定位置限制，否則查詢不會傳回所需結果。
「紐約的連鎖餐廳」	紐約有多個「連鎖餐廳」地點，但沒有街道地址，甚至連街道名稱都沒有。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」	英國埃舍市只有一條「High Street」，美國加州普萊森頓市也只有一條「Main Street」。
「UniqueRestaurantName New York」	紐約只有一家同名店面，因此不需要街道地址來區分。
「紐約的披薩餐廳」	這項查詢包含位置限制，「披薩餐廳」是明確定義的地點類型。並傳回多筆結果。
「[phone]」	這項查詢包含電話號碼。系統會傳回與該電話號碼相關聯的多個地點結果。 注意： 如要獲得最佳的電話號碼搜尋結果，請加入國家/地區代碼，並在後面加上空格，然後將 regionCode 參數設為對應的國家/地區代碼。電話號碼格式因國家/地區而異，API 會嘗試傳回這些不同格式的結果。

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

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

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

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

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

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
}

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 號」或「舊金山最佳景點」。

選用參數

使用 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 物件都可以包含出處和作者出處。如果應用程式會顯示評論，則也須顯示任何出處或作者出處資訊。

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