遷移至新版 Nearby Search

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

本頁面說明 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 (Legacy)

舊版「搜尋附近」可讓您依照關鍵字或類型，搜尋指定區域內的地點。您無法使用地點資料欄位限制搜尋，因此每次要求都會傳回所有可用欄位。以下程式碼片段顯示如何呼叫 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 (新版)

新版 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");
  }
}

瞭解詳情