Text Search (新版)

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

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

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

Text Search (新版) 與 Nearby Search (新版) 類似。兩者的主要差異在於，文字搜尋 (新版) 可讓您指定任意搜尋字串，而搜尋附近 (新版) 則需要指定特定搜尋區域。

「10 High Street, UK」或「123 Main Street, US」	英國有許多「High Street」；美國有許多「Main Street」。 除非設定位置限制，否則查詢不會傳回理想結果。
「ChainRestaurant New York」	紐約有多個「ChainRestaurant」地點，但沒有街道地址或街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」	英國城市埃舍 (Escher) 只有一個「High Street」；美國加州普萊森頓 (Pleasanton) 只有一個「Main Street」。
「UniqueRestaurantName New York」	紐約只有一家名稱相同的機構，因此不需要提供街道地址來區分。
「紐約市的披薩餐廳」	這個查詢包含位置限制，且「披薩餐廳」是明確定義的地點類型。會傳回多個結果。
「[phone]」	這個查詢包含電話號碼。這個 API 會傳回與該電話號碼相關聯的地點多筆結果。 注意： 如要針對電話號碼搜尋，請務必加入國家/地區代碼，並在後方加上空格，然後設定 region code 參數，以便對應國家/地區代碼。

注意： Text Search (New) 適用於 Places SDK for Android 3.3.0 以上版本。詳情請參閱「選擇 SDK 版本」。如要進一步瞭解如何使用在 4.0.0 版中新增的 Kotlin API，請參閱參考總覽。

文字搜尋要求

注意： 文字搜尋是 Places SDK for Android (新版) 的一部分，無法在 Places SDK for Android 中使用。

Text Search 要求的格式如下：

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

在本例中，您：

• 將欄位清單設為只包含 Place.Field.ID 和 Place.Field.DISPLAY_NAME。也就是說，回應中代表每個相符地點的 Place 物件只包含這兩個欄位。

• 使用 SearchByTextRequest.Builder 建立用於定義搜尋的 SearchByTextRequest 物件。

  • 將文字查詢字串設為「Spicy Vegetarian Food」。

  • 將結果地點數量上限設為 10。預設值和上限為 20。

  • 將搜尋區域限制在經緯度座標定義的矩形內。系統不會傳回超出此範圍的相符項目。

• 新增 OnSuccessListener，並從 SearchByTextResponse 物件取得相符的地點。

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱「初始化 Places API 用戶端」。

您可以使用 CancellationToken，嘗試取消對任何要求類別 (例如 FetchPlaceRequest) 的請求。系統會盡力取消。提出取消要求後，系統不會回覆。發出取消權杖並非保證特定要求會取消，而且即使沒有傳回回應，您仍可能會因要求而遭到收費。

文字搜尋回覆

SearchByTextResponse 類別代表搜尋要求的回應。SearchByTextResponse 物件包含：

• 代表所有相符地點的 Place 物件清單，每個相符地點對應一個 Place 物件。

• 每個 Place 物件只包含要求中傳遞的欄位清單所定義的欄位。

例如，您在要求中定義的欄位清單如下：

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

這個欄位清單表示回應中的每個 Place 物件只包含每個相符地點的地點 ID 和名稱。接著，您可以使用 Place.getId() 和 Place.getName() 方法，存取每個 Place 物件中的這些欄位。

如需更多 Place 物件資料欄位存取資料的範例，請參閱「存取 Place 物件資料欄位」

必要參數

SearchByTextRequest 的必要參數如下：

• 欄位清單

  指定要傳回的地點資料欄位。傳遞 Place.Field 值清單，指定要傳回的資料欄位。回應中沒有傳回欄位的預設清單。

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

  指定下列一或多個欄位：

  • 以下欄位會觸發 Text Search (ID Only) SKU：

    Place.Field.DISPLAY_NAME、Place.Field.ID、Place.Field.RESOURCE_NAME、
    
    注意事項：

    • Place.Field.NAME 欄位已在 Places SDK for Android 4.0 版中淘汰。改用 Place.Field.DISPLAY_NAME。
    • RESOURCE_NAME 欄位包含地點資源名稱，格式為 places/PLACE_ID。使用 DISPLAY_NAME 存取地點的文字名稱。

  • 以下欄位會觸發 Text Search (Basic) SKU：

    Place.Field.ACCESSIBILITY_OPTIONS、Place.Field.ADDRESS_COMPONENTS、Place.Field.ADR_FORMAT_ADDRESS、Place.Field.BUSINESS_STATUS、Place.Field.FORMATTED_ADDRESS、Place.Field.GOOGLE_MAPS_URI、Place.Field.ICON_BACKGROUND_COLOR、Place.Field.ICON_MASK_URL、Place.Field.LOCATION、Place.Field.PHOTO_METADATAS、Place.Field.PLUS_CODE、Place.Field.PRIMARY_TYPE、Place.Field.PRIMARY_TYPE_DISPLAY_NAME、Place.Field.SHORT_FORMATTED_ADDRESS、Place.Field.SUB_DESTINATIONS、Place.Field.TYPES、Place.Field.UTC_OFFSET、Place.Field.VIEWPORT
    
    注意：Place.Field.ADDRESS、Place.Field.ICON_URL、Place.Field.LAT_LNG 和 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE 欄位已在 Places SDK for Android 4.0 版中淘汰。請改用 Place.Field.FORMATTED_ADDRESS、Place.Field.ICON_MASK_URL、Place.Field.LOCATION 和 Place.ACCESSIBILITY_OPTIONS。Place.Field.ACCESSIBILITY_OPTIONS 僅適用於 Place Details (新版)。

  • 以下欄位會觸發 Text Search (Advanced) SKU：

    Place.Field.CURRENT_OPENING_HOURS、Place.Field.CURRENT_SECONDARY_OPENING_HOURS、Place.Field.INTERNATIONAL_PHONE_NUMBER、Place.Field.NATIONAL_PHONE_NUMBER、Place.Field.OPENING_HOURS、Place.Field.PRICE_LEVEL、Place.Field.RATING、Place.Field.SECONDARY_OPENING_HOURS、Place.Field.USER_RATING_COUNT、Place.Field.WEBSITE_URI、
    
    注意：Place.Field.PHONE_NUMBER 和 Place.Field.USER_RATINGS_TOTAL 欄位已在 Places SDK for Android 4.0 版中淘汰。請改用 Place.Field.INTERNATIONAL_PHONE_NUMBER 和 Place.USER_RATING_COUNT。

  • 以下欄位會觸發 Text Search (Preferred) SKU：

    Place.Field.ALLOWS_DOGS、Place.Field.CURBSIDE_PICKUP、Place.Field.DELIVERY、Place.Field.DINE_IN、Place.Field.EDITORIAL_SUMMARY、Place.Field.EV_CHARGE_OPTIONS、Place.Field.FUEL_OPTIONS、Place.Field.GOOD_FOR_CHILDREN、Place.Field.GOOD_FOR_GROUPS、Place.Field.GOOD_FOR_WATCHING_SPORTS、Place.Field.LIVE_MUSIC、Place.Field.MENU_FOR_CHILDREN、Place.Field.OUTDOOR_SEATING、Place.Field.PARKING_OPTIONS、Place.Field.PAYMENT_OPTIONS、Place.Field.RESERVABLE、Place.Field.RESTROOM、Place.Field.REVIEWS、Place.Field.SERVES_BEER、Place.Field.SERVES_BREAKFAST、Place.Field.SERVES_BRUNCH、Place.Field.SERVES_COCKTAILS、Place.Field.SERVES_COFFEE、Place.Field.SERVES_DESSERT、Place.Field.SERVES_DINNER、Place.Field.SERVES_LUNCH、Place.Field.SERVES_VEGETARIAN_FOOD、Place.Field.SERVES_WINE、Place.Field.TAKEOUT
  注意：Places SDK for Android 4.0 版已淘汰多個 Place 資料欄位，並新增其他欄位。詳情請參閱「遷移至 Places SDK for Android 4.0 中的新地點資料欄 」。

  如要設定欄位清單參數，請在建構 SearchByTextRequest 物件時呼叫 setPlaceFields() 方法。

• 文字查詢

  要搜尋的文字字串，例如「餐廳」、「中正路 123 號」或「舊金山最佳景點」。API 會根據這個字串傳回候選相符項目，並依據觀察到的關聯性排序結果。

  如要設定文字查詢參數，請在建構 SearchByTextRequest 物件時呼叫 setTextQuery() 方法。

選用參數

請使用 SearchByTextRequest 物件，指定要求的選用參數。

• 加入的類型

  將結果限制在符合 表 A 所定義的指定類型。只能指定一種類型。例如：

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  注意： 表格 B 中的值只會傳回在回應中。您無法使用 Table B 中的值做為篩選器。

  如要設定所包含的類型參數，請在建構 SearchByTextRequest 物件時呼叫 setIncludedType() 方法。

• 位置偏差

  指定要搜尋的區域。這個位置會做為偏差值，也就是說，系統可以傳回指定位置附近的結果，包括指定區域外的結果。

  您可以指定地點限制或地點偏好，但不能同時指定兩者。您可以將位置限制視為指定結果必須位於其中的區域，而位置偏好則是指定結果可能位於或位於附近的區域。請注意，使用位置偏好時，結果仍可能位於指定區域之外。

  注意： 如果您同時省略位置偏差和位置限制，API 預設會使用 IP 偏差。使用 IP 偏差時，API 會使用裝置的 IP 位址來偏差結果。
  注意： 如果 textQuery 包含明確的位置 (例如 Market in Barcelona)，系統就會覆寫 locationBias 參數。在這種情況下，系統會忽略 locationBias。

  將區域指定為矩形可視區域或圓形。

  • 圓形的定義是中心點和半徑 (以公尺為單位)。半徑必須介於 0.0 和 50000.0 之間 (含首尾)。例如：

    // Define latitude and longitude coordinates of the center of the search area.
    LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
    
    // Use the builder to create a SearchByTextRequest object.
    // Set the radius of the search area to 500.0 meters.
    final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
      .setMaxResultCount(10)
      .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
    

  • 矩形是經緯度可視區域，以兩個對角相反的低點和高點表示。低點代表矩形的西南角，高點則代表矩形的東北角。

    可視區域視為封閉區域，也就是包含邊界。緯度範圍必須介於 -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，則經度範圍為空白。

    必須填入低值和高值，且代表的方塊不得留空。空白的檢視區會導致錯誤。

    例如矩形檢視區，請參閱文字搜尋要求。

    如要設定位置偏差參數，請在建構 SearchByTextRequest 物件時呼叫 setLocationBias() 方法。

• 地區限制

  指定要搜尋的區域。系統不會傳回指定區域以外的結果。將區域指定為矩形可視區域。如要瞭解如何定義可視區域，請參閱「位置偏差」的說明。

  您可以指定地點限制或地點偏好，但不能同時指定兩者。您可以將位置限制視為指定結果必須位於其中的區域，而位置偏差則是指定結果必須位於附近，但可超出該區域的區域。

  注意： 如果您同時省略位置偏差和位置限制，API 預設會使用 IP 偏差。使用 IP 偏差時，API 會使用裝置的 IP 位址來偏差結果。

  如要設定位置限制參數，請在建構 SearchByTextRequest 物件時呼叫 setLocationRestriction() 方法。

• 結果數量上限

  指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設值) 之間。

  如要設定結果數上限參數，請在建構 SearchByTextRequest 物件時呼叫 setMaxResultCount() 方法。

• 最低評分

  限制結果只顯示平均使用者評分大於或等於此限制值的房源。值必須介於 0.0 至 5.0 (含) 之間，以 0.5 為單位遞增。例如：0、0.5、1.0、...、5.0 (含)。值會進位至最接近的 0.5。舉例來說，如果值為 0.6，系統就會排除所有評分低於 1.0 的結果。

  如要設定最低評分參數，請在建構 SearchByTextRequest 物件時呼叫 setMinRating() 方法。

• 營業中

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

  如要設定立即開啟參數，請在建構 SearchByTextRequest 物件時呼叫 setOpenNow() 方法。

• 價格等級

  根據預設，結果會包含提供所有價位服務的地點。如要限制結果只包含特定價格等級的地點，您可以傳遞一組整數值清單，這些值對應傳回地點的價格等級：

  • 1 - 地點提供低價服務。
  • 2 - 地點提供價格合理的服務。
  • 3 - 地點提供昂貴的服務。
  • 4 - 地點提供的服務價格非常昂貴。
  注意： 0 的整數值表示該地提供免費服務，可納入回應中，但無法用於要求中的篩選器值。

  如要設定價格層級參數，請在建構 SearchByTextRequest 物件時呼叫 setPriceLevels() 方法。

• 排名偏好設定

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

  • 如果是分類查詢 (例如「紐約市的餐廳」)，預設會使用 SearchByTextRequest.RankPreference.RELEVANCE (依搜尋關聯性排序結果)。您可以將排名偏好設定為 SearchByTextRequest.RankPreference.RELEVANCE 或 SearchByTextRequest.RankPreference.DISTANCE (依距離排名結果)。
  • 對於非分類查詢 (例如「Mountain View, CA」)，建議您不要設定排名偏好設定參數。

  如要設定排名偏好設定參數，請在建構 SearchByTextRequest 物件時呼叫 setRankPreference() 方法。

• 區域代碼

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

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

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

  如要設定區域代碼參數，請在建構 SearchByTextRequest 物件時呼叫 setRegionCode() 方法。

• 嚴格類型篩選

  與 include 類型參數搭配使用。設為 true 時，系統只會傳回符合包含類型所指定的指定類型地點。在 false (預設值) 的情況下，回應可能包含不符合指定類型的地點。

  如要設定嚴格類型篩選參數，請在建構 SearchByTextRequest 物件時呼叫 setStrictTypeFiltering() 方法。