Nearby Search (新版) 要求接受以圓形指定搜尋區域的輸入區域,由圓形中心點的經緯度座標和半徑 (單位為公尺) 定義。這項要求會傳回指定搜尋區域內的相符地點清單,每個地點皆以 Place
物件表示。
根據預設,回應會包含搜尋區域內所有類型的地點。 您可以選擇篩選回應,方法是指定要在回應中明確納入或排除的地點類型清單。舉例來說,您可以指定僅包含「餐廳」、「麵包店」和「咖啡廳」類型的回應,或是排除「學校」類型的所有地點。
Nearby Search (新版) 要求
呼叫 PlacesClient.searchNearby
並傳遞定義要求參數的 SearchNearbyRequest
物件,提出 Nearby Search (新版) 要求。
SearchNearbyRequest
物件會指定要求的所有必要及選用參數。必要參數包括:
Place
物件中要傳回的欄位清單,也稱為欄位遮罩。如果未在欄位清單中指定至少一個欄位,或省略欄位清單,則呼叫會傳回錯誤。- 搜尋區域的位置限制,定義為經緯度組合和半徑值 (以公尺為單位)。
這個鄰近的搜尋要求範例會指定回應 Place
物件包含搜尋結果中每個 Place
物件的地點欄位 Place.Field.ID
和 Place.Field.NAME
。還會篩選回應,只顯示「餐廳」和「咖啡廳」類型的地點,但排除「pizza_restaurant」和「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
物件。欄位遮蓋是不錯的設計做法,確保您不會要求不必要的資料,這有助於避免不必要的處理時間和帳單費用。指定下列一或多個欄位:
下列欄位會觸發 Nearby 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.ID
、Place.Field.NAME
、Place.Field.TYPES
、Place.Field.UTC_OFFSET
、Place.Field.VIEWPORT
、Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
下列欄位會觸發 Nearby 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
下列欄位會觸發 Nearby 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
如要設定欄位清單參數,請在建立
SearchNearbyRequest
物件時呼叫setPlaceFields()
方法。以下範例定義包含兩個欄位值的清單,指定要求傳回的
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);
地區限制
LocationRestriction
物件,定義要搜尋的區域,以圓形定義,並由中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間。請注意,如果指定太小的半徑,系統將傳回ZERO_RESULTS
做為回應。如要設定位置限制參數,請在建立
SearchNearbyRequest
物件時呼叫setLocationRestriction()
方法。
自選參數
請使用 SearchNearbyRequest
物件指定搜尋的選用參數。
-
類型和主要類型
您可以從表 A 類型中指定一份類型清單,用來篩選搜尋結果。每個類型限制類別最多可以指定 50 種類型。
一個地點只能有相關聯表 A 類型的單一主要類型。舉例來說,主要類型可能是
"mexican_restaurant"
或"steak_house"
。使用includedPrimaryTypes
和excludedPrimaryTypes
即可依地點主要類型篩選結果。單一地點也可以有與之表 A 類型相關聯的多個類型值。舉例來說,餐廳可以有下列類型:
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
。使用includedTypes
和excludedTypes
可篩選與地點相關聯的類型清單結果。如果搜尋具有多種類型限制,系統只會傳回符合所有限制的地點。舉例來說,如果您指定
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 (預設) 之間 (含 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 for Android 政策。