Text Search (新版)

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

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

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

「英國 10 號」或「美國中正路 123 號」 英國的多個「高街」；美國的多個「中正路」。 如未設定位置限制，查詢就不會傳回理想的結果。
「臺北市中餐廳」 紐約有多個「中菜餐廳」地點，沒有街道地址或街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 英國埃塞爾 (Escher) 的英國城市「高街」；在加州普萊桑頓市內只有一個「Main Street」(主街)。
「UniqueRestaurantName New York」 紐約只能有一間名稱的建築物，不需要街道地址即可區分。
「臺北市的披薩店」 這項查詢包含地點限制，而「披薩餐廳」是定義明確的地點類型。並傳回多項結果。
「+1 514-670-8700」

這項查詢包含電話號碼。並傳回多個與該電話號碼相關聯的地點結果。

Text Search 要求

Text Search 要求的格式為：

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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.NAME。這表示在代表每個相符地點的回應中，Place 物件只包含這兩個欄位。

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

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

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

    • 將搜尋區域限制在由經緯度座標定義的矩形中。沒有傳回這個區域以外的相符項目。

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

Text Search 回應

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

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

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

例如，您在請求中將欄位清單定義為：

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

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

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

必要參數

SearchByTextRequest 的必要參數如下：

  • 欄位清單

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

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

    指定下列一或多個欄位：

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

      Place.Field.ID、Place.Field.NAME

    • 下列欄位會觸發 Text Search (基本) SKU：

      Place.Field.ADDRESS_COMPONENTS、 Place.Field.BUSINESS_STATUS、 Place.Field.ADDRESS、 Place.Field.ICON_BACKGROUND_COLOR、 Place.Field.ICON_URL、 Place.Field.LAT_LNG、 Place.Field.PHOTO_METADATAS、 Place.Field.PLUS_CODE、 Place.Field.TYPES、 Place.Field.UTC_OFFSET、 Place.Field.VIEWPORT、 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • 下列欄位會觸發 Text Search (進階) SKU：

      Place.Field.CURRENT_OPENING_HOURS、 Place.Field.SECONDARY_OPENING_HOURS、 Place.Field.PHONE_NUMBER、 Place.Field.PRICE_LEVEL、 Place.Field.RATING、 Place.Field.OPENING_HOURS、 Place.Field.USER_RATINGS_TOTAL、 Place.Field.WEBSITE_URI

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

      Place.Field.CURBSIDE_PICKUP、 Place.Field.DELIVERY、 Place.Field.DINE_IN、 Place.Field.EDITORIAL_SUMMARY、 Place.Field.RESERVABLE、 Place.Field.REVIEWS、 Place.Field.SERVES_BEER、 Place.Field.SERVES_BREAKFAST、 Place.Field.SERVES_BRUNCH、 Place.Field.SERVES_DINNER、 Place.Field.SERVES_LUNCH、 Place.Field.SERVES_VEGETARIAN_FOOD、 Place.Field.SERVES_WINE、 Place.Field.TAKEOUT

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

  • 文字查詢

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

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

自選參數

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

  • 納入的類型

    將結果限制在符合表 A 定義的指定類型的地點。您只能指定一個類型。例如：

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

    如要設定隨附的類型參數，請在建立 SearchByTextRequest 物件時呼叫 setIncludedType() 方法。

  • 位置自訂調整

    指定要搜尋的區域。這個位置只是自訂調整，因此可傳回指定位置附近的結果，包括指定區域以外的結果。

    您可以指定位置限製或位置自訂調整，但不能同時指定兩者。您可以將位置限制視為指定結果所在的區域，以及位置自訂調整指定結果必須鄰近但可以超出該區域的區域。

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

    • 圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 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，緯度範圍會是空白。

      這個值必須填入下限和高，代表方塊不得留空。空白的可視區域會導致錯誤。

      舉例來說，如果是矩形可視區域，請參閱「Text Search 要求」。

      如要設定位置自訂調整參數，請在建立 SearchByTextRequest 物件時呼叫 setLocationBias() 方法。

  • 地區限制

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

    您可以指定位置限製或位置自訂調整，但不能同時指定兩者。您可以將位置限制視為指定結果所在的區域，以及位置自訂調整指定結果必須鄰近但可以超出該區域的區域。

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

  • 結果數量上限

    指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 之間 (含 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 - 地點提供價格高昂的服務。

    如要設定價格等級參數，請在建立 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() 方法。