遷移至新版 Nearby Search

本頁面說明 Place 類別 (新版) 和 PlacesService (舊版) 中使用的鄰近搜尋功能之間的差異，並提供一些程式碼片段供您比較。

  • 舊版 PlacesService 有 nearbySearch() 方法，可讓您依關鍵字或類型，搜尋指定區域內的地點。
  • Place 類別包含 searchNearby() 方法，可讓您依照地點類型搜尋指定區域內的地點，並利用擴充的地點資料欄位和地點類型選項，提供更彈性的搜尋方式。

下表列出 Place 類別與 PlacesService 之間附近搜尋方法的一些主要差異：

PlacesService (舊版) Place (新版)
nearbySearch()
 searchNearby()
PlaceSearchRequest SearchNearbyRequest
需要使用回呼來處理結果物件和 google.maps.places.PlacesServiceStatus 回應。 使用 Promise，並以非同步方式運作。
需要 PlacesServiceStatus 檢查。 不需要進行狀態檢查，可以使用標準錯誤處理。
僅支援位置偏差。 支援地點偏誤和地點限制。
傳回所有可用的資料欄位 (支援欄位的子集)；無法限制特定欄位。 只會傳回要求的地點資料欄位；Place 類別提供經常更新的擴充欄位選項。
僅限於固定的地點類型。 使用經常更新的擴充地點類型選項。
支援使用關鍵字進行文字搜尋。 不支援文字搜尋，請改用 Text Search (新版)。

程式碼比較

本節將比較附近搜尋方法的程式碼，說明 Places 服務和 Place 類別之間的差異。程式碼片段會顯示各個 API 需要的程式碼，以便發出文字搜尋要求。

Nearby Search (舊版)

舊版 Nearby Search 可讓您依照關鍵字或類型，搜尋指定區域內的地點。您無法使用地點資料欄位限制搜尋，因此每個要求都會傳回所有可用欄位。以下程式碼片段顯示呼叫 nearbySearch() 以傳回澳洲雪梨餐廳的相關資訊。這項要求是同步的，會使用回呼，並包含對 PlacesServiceStatus 的必要條件檢查。

let map;
let service;

function initMap() {
  const sydney = new google.maps.LatLng(-33.867, 151.195);

  map = new google.maps.Map(document.getElementById("map"), {
    center: sydney,
    zoom: 15,
  });

  const request = {
    location: sydney,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

// Helper function to create markers.
function createMarker(place) {
  if (!place.geometry || !place.geometry.location) return;

  const marker = new google.maps.Marker({
    map,
    position: place.geometry.location,
    title: place.name,
  });
}

瞭解詳情

Nearby Search (新版)

新版附近搜尋功能在以下方面改善了舊版的功能：

  • 可指定要傳回的地點資料欄位。
  • 使用可啟用非同步作業的 Promise。
  • 無須檢查 PlacesService 的狀態，可改用標準錯誤處理。

下列程式碼片段顯示函式，可針對餐廳提出鄰近搜尋要求。這個範例說明如何使用 rankPreference 選項，依熱門程度排序搜尋結果 (在先前版本中，排名是使用 rankBy 選項指定)。由於 searchNearby() 方法使用 await 運算子，因此只能在 async 函式內使用。

async function nearbySearch() {
  // Restrict within the map viewport.
  let center = new google.maps.LatLng(52.369358, 4.889258);
  const request = {
    // Required parameters.
    fields: ["displayName", "location", "businessStatus"],
    locationRestriction: {
      center: center,
      radius: 500,
    },
    // Optional parameters.
    includedPrimaryTypes: ["restaurant"],
    maxResultCount: 5,
    rankPreference: google.maps.places.SearchNearbyRankPreference.POPULARITY,
    language: "en-US",
    region: "us",
  };

  const { places } = await google.maps.places.Place.searchNearby(request);

  if (places.length) {
    console.log(places);

    // Create a new bounds, which will be extended with each result.
    const bounds = new google.maps.LatLngBounds();

    // Loop through and get all the results.
    places.forEach((place) => {
      const markerView = new google.maps.marker.AdvancedMarkerElement({
        map,
        position: place.location,
        title: place.displayName,
      });

      bounds.extend(place.location);
      console.log(place);
    });
    map.fitBounds(bounds);
  } else {
    console.log("No results");
  }
}

瞭解詳情