搜尋附近地點 (新)

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

搜尋附近地點 (新版) 要求接收區域輸入內容 指定為圓形，按經緯度定義 圓的中心點座標和半徑 (以公尺為單位)。 要求會傳回符合的地點清單，每個位置均以 Place敬上 物件，

根據預設，回應會包含搜尋區域內所有類型的地點。 您可以選擇將地點類型清單指定至目的地，藉此篩選回應。 明確包含在回應中或從中排除舉例來說，您可以指定 以僅包含「餐廳」類型的回應 「麵包店」和「咖啡店」，或是排除「學校」類型的所有地點。

Nearby Search (新版) 要求

透過呼叫提出 Nearby Search (新版) 要求 PlacesClient.searchNearby、 傳送 SearchNearbyRequest。 定義要求參數的物件。

SearchNearbyRequest 物件會指定所有必要和選用物件 參數。必要參數包括：

  • Place 物件中要傳回的欄位清單，也稱為 欄位遮罩如果未在欄位清單中指定至少一個欄位，或 如果您省略欄位清單，則呼叫會傳回錯誤。
  • 搜尋區域的地點限制，定義為 經緯度組合和半徑值 (以公尺為單位)。

這個鄰近的搜尋要求範例會指定回應 Place 物件 包含每個地點欄位 Place.Field.ID 和 Place.Field.NAME 搜尋結果中的 Place 物件。它也會篩選回覆 傳回「餐廳」類型的地點和「咖啡廳」，但排除類型的地點 「披薩餐廳」和「american_restaurant」

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Nearby Search (新版) 的回應

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

  • Place 物件清單，代表所有相符地點，其中有一個物件 每個相符地點的 Place 物件。
  • 每個 Place 物件都僅包含欄位清單定義的欄位 傳遞的內容。

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

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

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

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

必要參數

使用 SearchNearbyRequest敬上 物件，用於指定搜尋的必要參數。

  • 欄位清單

    要求 Place Details 時，您必須指定要傳回的資料， 地點的 Place 物件做為欄位遮罩。如要定義欄位遮罩，請將 值陣列 Place.Field敬上 至 SearchNearbyRequest 物件欄位遮蓋是不錯的設計做法 確保您不會要求不必要的資料。 不必要的處理時間和帳單費用

    指定下列一或多個欄位：

    • 下列欄位可觸發「搜尋附近」 (基本) 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.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE。

    • 下列欄位可觸發「搜尋附近」 (進階) 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

    • 下列欄位可觸發「搜尋附近」 (建議採用) 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。

    如要設定欄位清單參數，請呼叫 setPlaceFields()敬上 方法。SearchNearbyRequest

    以下範例定義包含兩個欄位值的清單，以便指定 要求傳回的 Place 物件包含 Place.Field.ID 和 Place.Field.NAME 欄位：

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

  • 地區限制

    A 罩杯 LocationRestriction敬上 物件，用於定義搜尋區域並指定為圓形 中心點和半徑 (單位為公尺)半徑值必須介於 1 至 之間 0.0 且小於或等於 50000.0，請注意，如果指定半徑太小 會以回應的形式傳回 ZERO_RESULTS。

    如要設定地點限制參數，請呼叫 setLocationRestriction()敬上 方法。SearchNearbyRequest

選用參數

使用 SearchNearbyRequest敬上 物件，用於指定搜尋的選用參數。

  • 類型和主要類型

    讓您從類型指定類型清單 表 A 用於篩選資料 搜尋結果每個類型限制類別最多可以指定 50 種類型。

    一個地點只能有單一主要類型類型 與表 A 相關聯的 基礎架構舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。使用 includedPrimaryTypes和excludedPrimaryTypes可篩選以下項目的結果 地點的主要類型

    一個地點也可以有類型及多個類型值 表 A 相關聯的資源例如，餐廳可能會有下列類型： "seafood_restaurant"、"restaurant"、"food"、 "point_of_interest"、"establishment"。使用「includedTypes」 和 excludedTypes，篩選與指定類別相關聯的類型清單結果 特定地點。

    指定一般主要類型時，例如 "restaurant" 或 "hotel"，回應可包含 將主要類型改為指定主要類型舉例來說，您指定 包括 "restaurant" 的主要類型。接著 包含主要類型為 "restaurant" 的地點，但是 回應也可能包含具有更明確主要類型的地點，例如 "chinese_restaurant" 或 "seafood_restaurant"。

    如果搜尋同時指定了多種類型限制，則只有地點 符合所有限制的條件都會傳回。舉例來說，假設您指定 includedTypes = Arrays.asList("restaurant") 和 excludedPrimaryTypes = Arrays.asList("steak_house")， 傳回的地點提供 "restaurant" 相關服務，但主要並非 做為 "steak_house"。

    如需 includedTypes 和 excludedTypes 的使用範例，請參閱 Nearby Search (新版) 要求。

    包含的類型

    地點類型的清單 表 A 搜尋。 如省略這個參數，系統會傳回所有類型的地點。

    如要設定包含的類型參數，請在建構 SearchNearbyRequest 物件時呼叫 setIncludedTypes() 方法。

    已排除的類型

    地點類型的清單 表 A：從指定目標中排除 搜尋。

    如果您同時指定 includedTypes (例如 "school") 和 excludedTypes (例如 "primary_school")，那麼 回應包含歸類為 "school" 但不接受的地點 "primary_school"。回應包含符合至少一個 includedTypes 和 無 excludedTypes。

    出現任何衝突的類型時，例如兩種類型都出現在 includedTypes 中 和 excludedTypes，會傳回 INVALID_REQUEST 錯誤。

    如要設定排除的類型參數，請在建構 SearchNearbyRequest 物件時呼叫 setExcludedTypes() 方法。

    包含的主要類型

    主要地點類型的清單 表 A 要納入 搜尋內容

    如要設定包含的主要類型參數，請在建立 SearchNearbyRequest 物件時呼叫 setIncludedPrimaryTypes() 方法。

    已排除的主要類型

    主要地點類型的清單 應排除的表 A 特定內容

    如果主要類型有相衝突的主要類型， includedPrimaryTypes 和 excludedPrimaryTypes， 傳回 INVALID_ARGUMENT 錯誤。

    如要設定排除的主要類型參數，請在建立 SearchNearbyRequest 物件時呼叫 setExcludedPrimaryTypes() 方法。

  • 結果數量上限

    指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 值，含首尾。

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

  • 排名偏好設定

    要使用的排名類型。如果省略這個參數，結果會按照熱門程度排名。 可以是下列其中一項：

    • POPULARITY (預設) 依據熱門程度將結果排序。
    • DISTANCE 依地點與 指定位置。

    如要設定排名偏好設定參數，請在建立 SearchNearbyRequest 物件時呼叫 setRankPreference() 方法。

  • 區域代碼

    用於設定回應格式的區碼，以 也就是雙字元 CLDR 代碼值。沒有預設值。

    如果回應中 formattedAddress 欄位的國家/地區名稱與 regionCode，formattedAddress 中省略了國家/地區代碼。

    大多數 CLDR 代碼 ISO 3166-1 代碼 有一些值得注意的例外情況舉例來說，英國的 ccTLD 是 「uk」(.co.uk)，但 ISO 3166-1 代碼卻是「gb」(技術上來說 「大不列顛暨北愛爾蘭聯合王國」)。 這個參數會根據適用法律影響結果。

    如要設定區碼參數，請在建立 SearchNearbyRequest 物件時呼叫 setRegionCode() 方法。

在應用程式中顯示作者資訊

應用程式顯示 PlacesClient、 (例如相片和評論)，應用程式也必須顯示必要的作者資訊。

詳情請參閱 Places SDK 政策 Android：