遷移至新版 Place Search

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

本頁面說明 Place 類別 (新版) 和 PlacesService (舊版) 中，以文字為基礎的地點搜尋功能之間的差異，並提供一些程式碼片段以供比較。

舊版 PlacesService 具有下列以文字為基礎的搜尋方法：

  • findPlaceFromQuery() 方法會接收文字查詢，並傳回單一地點結果，且支援使用地點資料欄位。
  • findPlaceFromPhoneNumber() 方法，可讓您使用電話號碼搜尋地點，並支援使用地點資料欄位。
  • textSearch() 方法會接收文字查詢，然後傳回地點結果清單。textSearch() 是較舊的 API，不支援使用地點資料欄位。

新的 Place 類別提供 Place.searchByText() 方法，可讓您使用文字查詢或電話號碼搜尋地點，並透過定期更新的擴大選取範圍，自訂搜尋地點資料欄位和地點類型。

下表列出 Place 類別和 PlacesService 的地點搜尋方法之間的一些主要差異：

PlacesService (舊版) Place (新)
findPlaceFromQuery()
findPlaceFromPhoneNumber() 		searchByText()
FindPlaceFromQueryRequest
FindPlaceFromPhoneNumberRequest		 SearchByTextRequest
查詢選項有限。 更多查詢選項。
必須使用回呼來處理結果物件和 google.maps.places.PlacesServiceStatus 回應。 使用 Promise，並以非同步方式運作。
需要 PlacesServiceStatus 檢查。 不需要檢查狀態，可使用標準錯誤處理程序。 瞭解詳情。
僅支援地點偏誤。 支援地點偏好設定和地點限制。
地點資料欄位的格式為蛇形命名法。 地點資料欄位的格式為駝峰式大小寫。
傳回單一地點結果。 最多傳回 20 個地點結果。
僅限一組固定的地點類型和地點資料欄位。 提供更多定期更新的地點類型和地點資料欄位。
textSearch()
 searchByText()
傳回所有可用的資料欄位 (支援欄位的子集)，無法限制為特定欄位。 只會傳回要求的地點資料欄位。

程式碼比較

本節將比較文字搜尋方法的程式碼，說明 Places Service 和 Place 類別之間的差異。程式碼片段會顯示各個 API 進行文字搜尋要求時所需的程式碼。

地點介面集服務 (舊版)

下列程式碼片段顯示如何使用 findPlaceFromQuery() 方法搜尋地點。這項要求是同步要求，且包含 PlacesServiceStatus 的條件式檢查。所需的地點資料欄位會指定在要求主體中，而要求主體是在發出實際要求前定義。

function findPlaces() {
  const request = {
    query: "Museum of Contemporary Art Australia",
    fields: ["name", "geometry"],
  };

  // Create an instance of PlacesService.
  service = new google.maps.places.PlacesService(map);

  // Make a findPlaceFromQuery request.
  service.findPlaceFromQuery(request, (results, status) => {
    let place = results[0];
    if (status === google.maps.places.PlacesServiceStatus.OK && results) {
      if (!place.geometry || !place.geometry.location) return;

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

瞭解詳情

Text Search (新版)

下列程式碼片段顯示如何使用 searchByText() 方法搜尋地點。這項要求是非同步要求，不需要檢查狀態 (可使用標準錯誤處理方式)。在本例中，要求包含 8 個 maxResultCount (值必須介於 1 到 20 之間)。這個函式會逐一處理結果，並為每個結果新增標記，然後根據標記位置調整地圖邊界。由於 searchByText() 方法使用 await 運算子，因此只能在 async 函式內使用。

async function findPlaces() {
  // Define a request.
  // The `fields` property is required; all others are optional.
  const request = {
    fields: ["displayName", "location", "businessStatus"],
    textQuery: "Tacos in Mountain View",
    includedType: "restaurant",
    locationBias: { lat: 37.4161493, lng: -122.0812166 },
    isOpenNow: true,
    language: "en-US",
    maxResultCount: 8,
    minRating: 3.2,
    region: "us",
    useStrictTypeFiltering: false,
  };

  // Call searchByText passing the request.
  const { places } = await google.maps.places.Place.searchByText(request);

  // Add a marker for each result.
  if (places.length) {
    const bounds = new google.maps.LatLngBounds();

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

相較於舊版，searchByText() 方法支援更多要求選項，包括：

  • includedType，可將搜尋範圍限制在特定地點類型。
  • isOpenNow，可將搜尋範圍限制為僅傳回營業中的地點。
  • minRating，可讓您篩除低於指定限制的結果 (例如，只傳回三顆星以上的地點)。
  • locationRestriction，可省略指定位置以外的結果 (也支援 locationBias)。

瞭解詳情