遷移至新版 Place Search

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

舊版 PlacesService 提供下列文字搜尋方法：

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

新的 Place 類別提供 Place.searchByText() 方法，可讓您使用文字查詢或電話號碼搜尋地點，並使用經常更新的地點資料欄位和地點類型，自訂搜尋內容。

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

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

程式碼比較

本節會比較文字搜尋方法的程式碼，說明 Places 服務和 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() 方法搜尋地點。這項要求是非同步的，因此不需要進行狀態檢查 (可使用標準錯誤處理)。在這個範例中，要求包含 maxResultCount 8 (值必須介於 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)。

瞭解詳情