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」 這項查詢包含電話號碼。Google 建議您在搜尋字串中加入國家/地區代碼,以改善搜尋品質。針對與該電話號碼相關聯的地點,傳回多筆結果。

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.IDPlace.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.IDPlace.Field.NAME
    • 下列欄位會觸發 Text Search (Basic) SKU

      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCEPlace.Field.ADDRESS_COMPONENTSPlace.Field.BUSINESS_STATUSPlace.Field.ADDRESSPlace.Field.ICON_BACKGROUND_COLORPlace.Field.ICON_URLPlace.Field.LAT_LNGPlace.Field.PHOTO_METADATASPlace.Field.PLUS_CODEPlace.Field.TYPESPlace.Field.UTC_OFFSETPlace.Field.VIEWPORT
    • 下列欄位會觸發 Text Search (Advanced) SKU

      Place.Field.CURRENT_OPENING_HOURSPlace.Field.SECONDARY_OPENING_HOURSPlace.Field.PHONE_NUMBERPlace.Field.PRICE_LEVELPlace.Field.RATINGPlace.Field.OPENING_HOURSPlace.Field.USER_RATINGS_TOTALPlace.Field.WEBSITE_URI
    • 下列欄位會觸發 Text Search (Preferred) SKU

      Place.Field.CURBSIDE_PICKUPPlace.Field.DELIVERYPlace.Field.DINE_INPlace.Field.EDITORIAL_SUMMARYPlace.Field.RESERVABLEPlace.Field.REVIEWSPlace.Field.SERVES_BEERPlace.Field.SERVES_BREAKFASTPlace.Field.SERVES_BRUNCHPlace.Field.SERVES_DINNERPlace.Field.SERVES_LUNCHPlace.Field.SERVES_VEGETARIAN_FOODPlace.Field.SERVES_WINEPlace.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)
        .setLocationRestriction(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 時,回應可能包含與指定類型不符的地點。