Text Search (新版)

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

Text Search (新版) 會傳回一組 以字串為依據的地點，例如「臺北市披薩」或鞋店 Ottawa 附近」或「中正路 123 號」。這項服務會傳回地點清單 。

這項服務在建立語意明確的地址時特別實用 查詢 字串中的非地址元件可能與商家 讓我們看看 DNS 解析 進一步探索內部和外部位址模稜兩可的地址查詢範例；地址格式有誤 或是內含非地址元件 (例如商家名稱) 的要求。要求數 除非是設定位置，否則前兩個範例可能不會傳回任何結果。 ，並設定地區、位置限製或位置自訂調整。

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

「英國 10 號高街」或「美國中正路 123 號」 英國的多個「高街」；美國境內的多個「主街」。 除非有地點限制，否則查詢不會傳回理想的結果 設定。
「臺北市中餐廳」 多個「中國餐廳」臺北市無街道地址， 甚至是街道名稱
「10 High Street, Escher UK」或「美國臺北市中正區 123 號」 只有一個「高街」；只有一個「中正路」 美國境內 Pleasanton 的用戶。
「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 (預設) 值，含首尾。

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

  • 最低評分

    限制只傳回使用者平均評分大於 的結果 或等於此上限這個值必須介於 0.0 和 5.0 (含) 之間 整數值。例如：0、0.5、1.0、...、5.0 (含)。值為 會四捨五入至最接近的 0.5。舉例來說，如果值是 0.6，就會排除所有 評分低於 1.0 的結果

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

  • 營業中

    如果true，請只傳回營業中的地點 寫入時。如果false，請退回所有商家 不論是否開啟狀態 在 Google 地點介面集資料庫中，未指定營業時間的地點，就是 如果您將這個參數設為 false，就會傳回 。

    如要設定開放立即使用的參數，請在建構 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() 方法。