迁移到新版地点搜索

欧洲经济区 (EEA) 开发者

本页面介绍了 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 检查。 无需进行状态检查，可以使用标准错误处理。 了解详情。
仅支持位置偏差。 支持位置偏差和位置限制。
地点数据字段采用蛇形命名法。 地点数据字段采用驼峰式命名法。
返回单个地点结果。 返回最多 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);
    }
  });
}

了解详情

文本搜索（新）

以下代码段展示了如何使用 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）。

了解详情