本頁面由 Cloud Translation API 翻譯而成。

Nearby Search (新版)

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

Nearby Search (新版) 要求會將要搜尋的區域做為輸入內容，並以圓形表示，該圓形的定義是圓心經緯度座標和半徑 (以公尺為單位)。這項要求會傳回符合條件的地點清單，每個地點都由 Place 物件代表，位於指定搜尋範圍內。

根據預設，回應會包含搜尋區域內的所有類型地點。您可以選擇篩選回應，方法是指定要明確納入或排除回應中的地點類型清單。舉例來說，您可以指定回應中只包含類型為「餐廳」、「烘焙坊」和「咖啡廳」的場所，或是排除所有類型為「學校」的場所。

Nearby Search (新版) 要求

呼叫 PlacesClient.searchNearby，傳遞定義要求參數的 SearchNearbyRequest 物件，即可發出 Nearby Search (新版) 要求。

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

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

這個附近搜尋要求範例會指定回應 Place 物件包含搜尋結果中每個 Place 物件的地點欄位 Place.Field.ID 和 Place.Field.DISPLAY_NAME。它也會篩選回應，只傳回類型為「restaurant」和「cafe」的場地，但排除類型為「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.DISPLAY_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();
    });

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱「初始化 Places API 用戶端」。

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 物件資料欄位存取資料的範例，請參閱「存取 Place 物件資料欄位」。

必要參數

使用 SearchNearbyRequest 物件指定搜尋作業的必要參數。

欄位清單

要求地點詳細資料時，您必須在 Place 物件中指定要傳回的地點資料，做為欄位遮罩。如要定義欄位遮罩，請將值陣列從 Place.Field 傳遞至 SearchNearbyRequest 物件。欄位遮罩是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

指定下列一或多個欄位：
- 下列欄位會觸發 Nearby Search Pro 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.PRIMARY_TYPE
  Place.Field.PRIMARY_TYPE_DISPLAY_NAME
  Place.Field.ID
  Place.Field.NAME
  Place.Field.TYPES
  Place.Field.UTC_OFFSET
  Place.Field.VIEWPORT
  Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
- 下列欄位會觸發 Nearby Search Enterprise SKU：
  Place.Field.CURRENT_OPENING_HOURS
  Place.Field.CURRENT_SECONDARY_OPENING_HOURS
  Place.Field.INTERNATIONAL_PHONE_NUMBER
  Place.Field.NATIONAL_PHONE_NUMBER
  Place.Field.OPENING_HOURS
  Place.Field.PRICE_LEVEL
  Place.Field.RATING
  Place.Field.SECONDARY_OPENING_HOURS
  Place.Field.USER_RATING_COUNT
  Place.Field.WEBSITE_URI
  
  已淘汰的欄位：Place.Field.PHONE_NUMBER 和 Place.Field.USER_RATINGS_TOTAL 欄位已在 Places SDK for Android 4.0 版淘汰。請改用 Place.Field.INTERNATIONAL_PHONE_NUMBER 和 Place.USER_RATING_COUNT。
- 下列欄位會觸發 Nearby Search Enterprise Plus SKU：
  Place.Field.ALLOWS_DOGS
  Place.Field.CURBSIDE_PICKUP
  Place.Field.DELIVERY
  Place.Field.DINE_IN
  Place.Field.EDITORIAL_SUMMARY
  Place.Field.EV_CHARGE_OPTIONS
  Place.Field.FUEL_OPTIONS
  Place.Field.GOOD_FOR_CHILDREN
  Place.Field.GOOD_FOR_GROUPS
  Place.Field.GOOD_FOR_WATCHING_SPORTS
  Place.Field.LIVE_MUSIC
  Place.Field.MENU_FOR_CHILDREN
  Place.Field.OUTDOOR_SEATING
  Place.Field.PARKING_OPTIONS
  Place.Field.PAYMENT_OPTIONS
  Place.Field.RESERVABLE
  Place.Field.RESTROOM
  Place.Field.REVIEWS
  Place.Field.SERVES_BEER
  Place.Field.SERVES_BREAKFAST
  Place.Field.SERVES_BRUNCH
  Place.Field.SERVES_COCKTAILS
  Place.Field.SERVES_COFFEE
  Place.Field.SERVES_DESSERT
  Place.Field.SERVES_DINNER
  Place.Field.SERVES_LUNCH
  Place.Field.SERVES_VEGETARIAN_FOOD
  Place.Field.SERVES_WINE
  Place.Field.TAKEOUT
注意：Places SDK for Android 4.0 版本淘汰了幾個 Place 資料欄位，並新增了新的欄位。詳情請參閱「遷移至 Places SDK for Android 4.0 中的新地點資料欄」。
如要設定欄位清單參數，請在建構 SearchNearbyRequest 物件時呼叫 setPlaceFields() 方法。

以下範例會定義兩個欄位值清單，指定要求傳回的 Place 物件包含 Place.Field.ID 和 Place.Field.DISPLAY_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.DISPLAY_NAME);

地區限制

LocationRestriction 物件會將要搜尋的區域定義為圓形，並以圓心和半徑 (以公尺為單位) 定義圓形。半徑必須大於 0.0，且小於或等於 50000.0，請注意，如果指定的半徑太小，系統會將 ZERO_RESULTS 做為回應。

如要設定位置限制參數，請在建構 SearchNearbyRequest 物件時呼叫 setLocationRestriction() 方法。

選用參數

使用 SearchNearbyRequest 物件指定搜尋的選用參數。

類型和主要類型

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

注意： 表格 B 中的值只會在回應中傳回。您無法使用 Table B 中的值做為篩選器。
地點只能有 單一主要類型，且該類型必須與表格 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、includedPrimaryTypes 和 excludedPrimaryTypes，搜尋結果會傳回位置限制範圍內的所有類型地點。

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

加入的類型

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

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

已排除的類型

表 A 中要排除的場所類型清單。

如果您在要求中同時指定 includedTypes (例如 "school") 和 excludedTypes (例如 "primary_school")，回應就會包含歸類為 "school" 但非 "primary_school" 的 Places。回應會包含與 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 代碼值。沒有預設值。

如果回應中 FORMATTED_ADDRESS 欄位的國家/地區名稱與 regionCode 相符，FORMATTED_ADDRESS 就會省略國家/地區代碼。

大多數 CLDR 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。這個參數可能會影響根據適用法律產生的結果。

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

在應用程式中顯示出處資訊

如果應用程式會顯示從 PlacesClient 取得的資訊 (例如相片和評論)，則也必須顯示必要的出處資訊。

詳情請參閱「Places SDK for Android 的政策」。

Nearby Search (新版)

Nearby Search (新版) 要求

Nearby Search (新版) 回應

必要參數

欄位清單

地區限制

選用參數

類型和主要類型

加入的類型

已排除的類型

已納入的主要類型

已排除的主要類型

結果數量上限

排名偏好設定

區域代碼

在應用程式中顯示出處資訊