地点库

概览

借助 Maps JavaScript API 地点库中的功能，您的应用可以搜索指定区域（例如地图的边界或固定点周围）内包含的地点（在此 API 中定义为场所、地理位置或著名地图注点）。

Places API 提供了自动补全功能，您可以利用此功能让自己的应用具有 Google 地图搜索字段的“即输即找”功能。当用户开始输入地址时，自动补全功能将会填充其余部分。如需了解详情，请参阅介绍自动补全的说明文档。

开始使用

如果您不熟悉 Maps JavaScript API 或 JavaScript，建议您在开始使用之前先查看 JavaScript 并获取 API 密钥。

加载库

地点服务是一个独立于 Maps JavaScript API 主代码的自足库。如需使用此库中包含的功能，您必须先在 Maps API 引导程序网址中使用 libraries 参数加载该库。

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

如需了解详情，请参阅库概览。

将 Places API 添加到 API 密钥的 API 限制列表

1. 前往 Google Cloud 控制台。
2. 点击项目下拉菜单，选择您想保护的 API 密钥所在的项目。
3. 点击菜单按钮 ，然后依次选择 Google Maps Platform > 凭据。
4. 在凭据页面上，点击要保护的 API 密钥的名称。
5. 在限制和重命名 API 密钥页面上，设置以下限制：
   
   • API 限制
   • 选择限制密钥。
   • 点击选择 API，然后选择 Maps JavaScript API 和 Places API。
     （如果未列出其中任何一个 API，您需要启用它。）
6. 点击保存。

用量限额和政策

配额

地点库与 Places API 共享用量配额，具体说明见 Places API 的用量限额文档。

政策

使用 Maps JavaScript API 地点库时，必须遵守适用于 Places API 的政策。

地点搜索

借助地点服务，您可以执行以下类型的搜索：

• 通过查询查找地点会根据文本查询返回地点（例如某个地点的名称或地址）。
• 通过电话号码查找地点会根据电话号码返回地点。
• 附近搜索会根据用户所在位置返回附近的地点列表。
• 文本搜索会根据搜索字符串（例如“披萨”）返回附近的地点列表。
• “地点详情”请求会返回有关特定地点的更多详细信息，包括用户评价。

返回的信息可能包括餐馆、商店和办公地点等场所，以及“地理编码”结果。“地理编码”结果表示地址、政治区域（例如城镇和城市）及其他地图注点。

“查找地点”请求

借助“查找地点”请求，您可以通过文本查询或电话号码搜索地点。“查找地点”请求分为两类：

• 通过查询查找地点
• 通过电话号码查找地点

通过查询查找地点

“通过查询查找地点”会根据用户输入的文本返回地点。可以输入任何类型的地点数据，例如商家名称或地址。如需发出“通过查询查找地点”请求，请调用 PlacesService 的 findPlaceFromQuery() 方法，该方法采用以下参数：

• query（必需）：要用作搜索条件的文本字符串，例如“餐馆”或“长安街 123 号”。该参数必须是地点名称、地址或场所类别。任何其他类型的输入都可能产生错误，并且不能保证返回有效结果。Places API 将根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。
• fields（必需）：一个或多个字段，用于指定要返回的地点数据类型。
• locationBias（可选）：用于指定搜索区域的坐标。可以是以下其中一项：
  • 以 LatLngLiteral 或 LatLng 对象形式指定的一组纬度/经度坐标
  • 矩形边界（两对纬度/经度，或一个 LatLngBounds 对象）
  • 以纬度/经度为中心的半径范围（以米为单位）

您还必须向 findPlaceFromQuery() 传递一个回调方法，以处理结果对象和 google.maps.places.PlacesServiceStatus 响应。

以下示例展示了对 findPlaceFromQuery() 的调用，搜索的是“Museum of Contemporary Art Australia”（澳大利亚当代艺术博物馆），具体包含 name 和 geometry 字段。

var map;
var service;
var infowindow;

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

  infowindow = new google.maps.InfoWindow();

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

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}

通过电话号码查找地点

“通过电话号码查找地点”会利用电话号码返回地点。如需发出“通过电话号码查找地点”请求，请调用 PlacesService 的 findPlaceFromPhoneNumber() 方法，该方法采用以下参数：

• phoneNumber（必需）：电话号码，采用 E.164 格式。
• fields（必需）：一个或多个字段，用于指定要返回的地点数据类型。
• locationBias（可选）：用于定义搜索区域的坐标。可以是以下其中一项：
  • 以 LatLngLiteral 或 LatLng 对象形式指定的一组纬度/经度坐标
  • 矩形边界（四个纬度/经度点，或一个 LatLngBounds 对象）
  • 以纬度/经度为中心的半径范围（以米为单位）

您还必须向 findPlaceFromPhoneNumber() 传递一个回调方法，以处理结果对象和 google.maps.places.PlacesServiceStatus 响应。

字段（“查找地点”方法）

使用 fields 参数指定要返回的地点数据类型的数组。例如：fields: ['formatted_address', 'opening_hours', 'geometry']。指定复合值时，请使用点。例如：opening_hours.weekday_text。

这些字段与“地点搜索”结果相对应，而且分为三个结算类别：基本、联系人和氛围。“基本”字段按基本费率结算，且不会产生额外费用。“联系人”和“氛围”字段按更高的费率结算。如需了解详情，请参阅定价表。无论是否针对此字段发出请求，每次调用都会返回提供方 (html_attributions) 说明。

基本

“基本”类别包括以下字段：
business_status、formatted_address、geometry、icon、icon_mask_base_uri、icon_background_color、name、permanently_closed（已弃用）、photos、place_id、plus_code、types

联系人

氛围

findPlaceFromQuery() 和 findPlaceFromPhoneNumber() 方法采用同一组字段，可能会在各自的响应中返回相同的字段。

设置位置偏向（“查找地点”方法）

使用 locationBias 参数可使“查找地点”优先考虑特定区域的结果。您可以通过以下方式设置 locationBias：

使结果偏向于特定区域：

locationBias: {lat: 37.402105, lng: -122.081974}

定义要搜索的矩形区域：

locationBias: {north: 37.41,