Nearby Search (新版)

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

歐洲經濟區 (EEA) 開發人員

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

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

Nearby Search (新版) 要求

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

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

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

這個附近的搜尋要求範例指定回應 Place 物件包含地點欄位 Place.Field.ID 和 Place.Field.DISPLAY_NAME，適用於搜尋結果中的每個 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.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();
    });

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 物件中，以欄位遮罩的形式指定要傳回的資料。如要定義欄位遮罩，請將 Place.Field 的值陣列傳遞至 SearchNearbyRequest 物件。欄位遮罩是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

    指定下列一或多個欄位：

    • 下列欄位會觸發 Nearby Search Pro SKU：

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * 請改用這個標記，Place.Field.NAME 已淘汰。
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * 請改用這個函式，因為 Place.Field.ICON_URL 已淘汰。
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • 下列欄位會觸發鄰近搜尋企業 SKU：

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * 請改用這個函式，因為 Place.Field.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.USER_RATINGS_TOTAL 已淘汰。
      Place.Field.WEBSITE_URI

    • 下列欄位會觸發鄰近搜尋 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

    如要設定欄位清單參數，請在建構 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 物件指定搜尋的選用參數。

  • 類型和主要類型

    可讓您指定類型清單 (來自類型 表 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。 如果省略這個參數，系統會傳回所有類型的地點。

    如要設定 included types 參數，請在建構 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)，預設為 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 政策」。