Text Search (新版)

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.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 物件資料的範例,請參閱「存取地點」 物件資料欄位

必要參數

如要使用 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.RELEVANCESearchByTextRequest.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() 方法。