Text Search

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

此服務特別適合用於自動化系統中模糊的地址查詢，且字串的非地址元件可能與商家和地址相符。模稜兩可的地址查詢範例包括格式不正確的地址，或是包含非地址元件 (例如商家名稱) 的要求。前兩個範例的要求可能會傳回零結果，除非已設定位置 (例如區域、位置限製或位置自訂調整)。

「10 High Street, UK」或「123 Main Street, US」 英國有多個「高街」，美國境內還有多條「主要街道」。 除非已設定位置限制，否則查詢不會傳回符合需求的結果。
「臺北中國菜」 在紐約有多個「連鎖餐廳」地點；沒有街道地址或甚至街道名稱。
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 英國 Escher 城市中只有一號「高街」，在美國普萊森頓市只有一道「主要街道」。
「Unique 餐廳 Name 紐約」 在紐約只使用一間名稱的建築物，不需要區分街道地址。
「臺北披薩餐廳」 這項查詢包含地點限制，而「披薩餐廳」是定義明確的地點類型。這個方法會傳回多個結果。
「+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 物件中資料的更多範例，請參閱「存取地點物件資料欄位」一文

必要參數

  • 欄位清單

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

    欄位清單是不錯的設計做法，可避免要求不必要的資料，避免不必要的處理時間和帳單費用。

    請指定下列一或多個欄位：

    • 下列欄位會觸發文字搜尋 (僅限 ID) SKU：

      Place.Field.ID、Place.Field.NAME

    • 下列欄位會觸發 Text Search (Basic) 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 (Advanced) 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

  • 文字查詢

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

自選參數

使用 SearchByTextRequest.Builder 的方法設定這些參數。舉例來說，如要設定結果數量上限，請呼叫 SearchByTextRequest.Builder.setMaxResultCount()。

  • 包含的類型

    讓系統在結果中只限於符合表 A 定義的指定類型的地點。只能指定一種類型。例如：

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

  • 位置自訂調整

    指定要搜尋的區域。這個位置可以做為自訂調整，這表示系統會傳回指定位置周圍的結果，包括指定區域以外的結果。

    您可以指定位置限製或位置自訂調整，但只能擇一。請將位置限制視為指定結果必須落在哪個區域，以及位置自訂調整，就像指定結果的附近地區，但可以位於該區域之外。

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

    • 圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 0.0 到 50000.0 (含) 之間。預設半徑為 0.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，則緯度範圍是空白。

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

      以矩形可視區域為例，請參閱「搜尋文字要求」。

  • 地區限制

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

    您可以指定位置限製或位置自訂調整，但只能擇一。位置限制就像是指定結果所在的區域，以及位置自訂調整，就像指定結果的附近地區，但可以位於該區域之外。

  • 結果數量上限

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

  • 最低評分

    限制系統只傳回使用者平均評分大於或等於這個上限的結果。值必須介於 0.0 至 5.0 (含) 之間，以 0.5 為單位。例如：0、0.5、1.0、...、5.0 (含頭尾)。值會無條件進位至最接近的 0.5 倍數。舉例來說，如果值為 0.6，則會排除評分小於 1.0 的所有結果。

  • 營業中

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

  • 價位

    將搜尋範圍限制在特定價格等級的地點。 預設設定是選取所有價位。

    指定以下一或多個整數值的清單：

    • 1 - PRICE_LEVEL_INEXPENSIVE
    • 2 - PRICE_LEVEL_MODERATE
    • 3 至 PRICE_LEVEL_EXPENSIVE 個
    • 4 - PRICE_LEVEL_VERY_EXPENSIVE

  • 排名偏好

    指定結果在回應中的排名方式。根據預設，API 會使用 RELEVANCE (如適用)。舉例來說，如果是「臺北餐廳」這類查詢，則預設值為 RELEVANCE。如果是地理區域查詢 (例如「加州山景城」)，或其他類型的查詢，系統不會套用任何預設值，而且結果會依照後端傳回的順序顯示。

    相關的值包括：

    • SearchByTextRequest.RankPreference.DISTANCE：按照距離排名結果。
    • SearchByTextRequest.RankPreference.RELEVANCE：依關聯性將結果排名。

  • 區域代碼

    用於設定回應格式的區碼，指定為 雙字元 CLDR 代碼值。此外，這項參數也會對搜尋結果產生偏誤。沒有預設值。

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

    大多數 CLDR 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律，這個參數可能會影響結果。

  • 嚴格類型篩選

    與 include 類型參數搭配使用。如果設為 true，系統只會傳回與納入類型指定類型相符的地點。預設值為 false 時，回應可能包含與指定類型不符的地點。