地点库

概览

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

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

开始使用

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

启用 API

在使用 Maps JavaScript API 中的地点库之前，请先确保在 Google Cloud 控制台中针对您为 Maps JavaScript API 设置的同一项目启用了 Places API。

若要查看已启用的 API 列表，请按以下步骤操作：

  1. 前往 Google Cloud 控制台。
  2. 点击选择项目按钮，选择您为 Maps JavaScript API 设置的同一项目，然后点击打开。
  3. 在信息中心上的 API 列表中，查找 Places API。
  4. 如果您在列表中看到 Places API，就说明已启用此 API。如果未看到该 API，请按以下步骤启用它：
    1. 在页面顶部，选择启用 API 和服务以显示库标签页。或者，您也可以从左侧菜单中选择库。
    2. 搜索 Places API，然后从结果列表中选择它。
    3. 选择启用。该过程完成后，Places API 即会显示在信息中心上的 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 限制列表

针对密钥应用 API 限制后，只有一个或多个 API 或 SDK 可以使用 API 密钥。系统会处理针对与 API 密钥关联的 API 或 SDK 发出的请求。针对未与 API 密钥关联的 API 或 SDK 发出的请求将会失败。如需限定某个 API 密钥只能用于 Maps JavaScript 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（可选）：用于指定搜索区域的坐标。可以是以下其中一项：

您还必须向 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（可选）：用于定义搜索区域的坐标。可以是以下其中一项：

您还必须向 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

联系人

“联系人”类别包括以下字段： opening_hours
（在 Maps JavaScript API 地点库中已弃用。使用“地点详情”请求获取 opening_hours 结果）。

氛围

“氛围”类别包括以下字段： price_level、rating、user_ratings_total

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

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

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

使结果偏向于特定区域：

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

定义要搜索的矩形区域：

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

您也可以使用 LatLngBounds。

定义要搜索的半径范围（以米为单位），该范围以特定区域为中心：

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

“附近搜索”请求

通过“附近搜索”，您可以根据关键字或类型搜索指定区域内的地点。“附近搜索”必须始终包含一个位置，可以通过以下两种方式之一来指定该位置：

  • 使用 LatLngBounds。
  • 通过 location 属性（使用 LatLng 对象指定圆心）和半径（以米为单位）的组合定义的圆形区域。

您可以调用 PlacesService 的 nearbySearch() 方法发起“地点 - 附近搜索”，该方法将返回 PlaceResult 对象的数组。请注意，从版本 3.9 开始，nearbySearch() 方法将取代 search() 方法。

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

此方法可接收包含以下字段的请求：

  • 以下两个字段之一：
    • bounds，它必须是用于定义矩形搜索区域的 google.maps.LatLngBounds 对象。边界区域支持的对角线距离上限约为 10 万米。
    • location 和 radius，前者采用 google.maps.LatLng 对象，后者采用简单的整数，代表圆形区域的半径范围（以米为单位）。允许的最大半径范围为 50,000 米。请注意，将 rankBy 设置为 DISTANCE 时，您必须指定 location，但不能指定 radius 或 bounds。
  • keyword（可选）- 要与所有可用字段进行匹配的字词，包括但不限于名称、类型和地址，以及客户评价和其他第三方内容。
  • minPriceLevel 和 maxPriceLevel（可选）- 将结果限制为仅包含指定范围内的地点。有效值的范围介于 0（最实惠）和 4（最昂贵）之间，包括 0 和 4。
  • name 已弃用。等同于 keyword。此字段中的值会与 keyword 字段中的值合并，作为同一搜索字符串的一部分进行传递。
  • openNow（可选）- 一个布尔值，表示地点服务应仅返回那些在发送查询时开门营业的地点。如果您在查询中包含此参数，系统不会返回那些未在 Google 地点数据库中指定营业时间的地点。将 openNow 设置为 false 不会产生任何影响。
  • rankBy（可选）- 指定结果的排列顺序。可能的值包括：
    • google.maps.places.RankBy.PROMINENCE（默认）。此选项可根据重要性对结果排序。系统会优先列出指定半径范围内的知名地点，而不是虽然匹配但不那么知名的附近地点。知名度受 Google 索引中的地点排名、全球知名度和其他因素的影响。指定 google.maps.places.RankBy.PROMINENCE 时，必须提供 radius 参数。
    • google.maps.places.RankBy.DISTANCE。此选项根据结果与指定的 location（必需）之间的距离按升序对结果进行排序。请注意，如果指定 RankBy.DISTANCE，则不能指定自定义 bounds 和/或 radius。当您指定 RankBy.DISTANCE 时，必须提供一个或多个 keyword、name 或 type。
  • type - 将结果限制为与指定类型相匹配的地点。只能指定一个类型（如果提供多个类型，系统会忽略第一个条目之后的所有类型）。请参阅支持的类型列表。

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

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

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

  var request = {
    location: pyrmont,
    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]);
    }
  }
}

查看示例

“文本搜索”请求

Google 地点文本搜索服务是一项网络服务，可以根据一个字符串（例如，“北京烤鸭”或“南京附近的鞋店”）返回一组地点的相关信息。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。搜索响应将包含一个地点列表。如需详细了解响应中的任何地点，您可以发送“地点详情”请求。

您可以调用 PlacesService 的 textSearch() 方法发起“文本搜索”。 

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

此方法可接收包含以下字段的请求：

  • query（必需）：要搜索的文本字符串，例如“餐馆”或“长安街 123 号”。该参数必须是地点名称、地址或场所类别。任何其他类型的输入都可能产生错误，并且不能保证返回有效结果。地点服务将根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。如果搜索请求中还使用了 type 参数，该参数会变为可选参数。
  • 可选：
    • openNow - 一个布尔值，表示地点服务应仅返回那些在发送查询时开门营业的地点。如果您在查询中包含此参数，系统不会返回那些未在 Google 地点数据库中指定营业时间的地点。将 openNow 设置为 false 不会产生任何影响。
    • minPriceLevel 和 maxPriceLevel - 将结果限制为仅包含指定价位内的地点。有效值范围介于 0（最实惠）和 4（最昂贵）之间，包括 0 和 4。
    • 以下两个字段之一：
      • bounds，它必须是用于定义矩形搜索区域的 google.maps.LatLngBounds 对象。边界区域支持的对角线距离上限约为 10 万米。
      • location 和 radius - 您可以传递 location 和 radius 参数，使结果偏向指定圆形区域。这将指示地点服务优先显示该圆形区域内的结果。指定区域以外的结果可能仍会显示。 location 采用 google.maps.LatLng 对象，radius 采用简单的整数，表示圆形区域的半径范围（以米为单位）。允许的最大半径范围为 50,000 米。
    • type - 将结果限制为与指定类型相匹配的地点。只能指定一个类型（如果提供多个类型，系统会忽略第一个条目之后的所有类型）。请参阅支持的类型列表。

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

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

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

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

搜索响应

状态代码

PlacesServiceStatus 响应对象包含请求的状态，可能还包含调试信息，以帮助您跟踪地点请求失败的原因。可能的状态值包括：

  • INVALID_REQUEST：该请求无效。
  • OK：响应中包含有效的结果。
  • OVER_QUERY_LIMIT：网页已超出其请求配额。
  • REQUEST_DENIED：不允许网页使用 PlacesService。
  • UNKNOWN_ERROR：由于服务器错误，无法处理 PlacesService 请求。如果您重试一次，请求可能会成功。
  • ZERO_RESULTS：找不到关于此请求的任何结果。

“地点搜索”结果

findPlace()、nearbySearch() 和 textSearch() 函数会返回 PlaceResult 对象的数组。

每个 PlaceResult 对象可能都包含以下属性：

  • business_status 表示地点的营业状态（如果该地点为商家）。它可以包含以下其中一个值：
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    如果不存在任何数据，将不会返回 business_status。
  • formatted_address 是一个字符串，包含此地点直观易懂的地址。系统仅会针对文本搜索返回 formatted_address 属性。

    此地址通常相当于邮政地址。请注意，由于许可限制，某些国家/地区（例如英国）不允许发布真实的邮政地址。

    设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如，地址“111 8th Avenue, New York, NY”包含以下组成部分：“111”（门牌号）、“8th Avenue”（道路名称）、“New York”（城市）和“NY”（美国州名）。

    请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分，API 响应除了包含设有格式的地址字段外，还包含这些组成部分。

  • geometry：地点的几何图形相关信息。其中包括：
    • location 提供该地点的纬度和经度。
    • viewport 定义查看该地点时地图上的首选视口。
  • permanently_closed（已弃用）是一个布尔值标记，表示该地点是已永久停业还是暂时停业（值为 true）。请勿使用 permanently_closed，建议改用 business_status 来获取商家的营业状态。
  • plus_code（请参阅 Open Location Code 和 Plus Codes）是经过编码的位置引用，衍生自纬度和经度坐标，表示面积不超过 1/8,000 度 x 1/8,000 度（在赤道处约为 14 米 x 14 米）的区域。Plus Codes 可用于在没有街道地址的地点（例如建筑物未编号，或者街道未命名）取代街道地址。

    Plus Code 的格式包括全局代码和混合代码：

    • global_code 是包含 4 个字符的区号和至少包含 6 个字符的区域代码 (849VCWC8+R9)。
    • compound_code 是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9, Mountain View, CA, USA）。请勿以程序化方式解析此内容。
    通常情况下，系统会返回全局代码和混合代码。但是，如果结果是在偏远位置（例如海洋或沙漠），系统可能只会返回全局代码。
  • html_attributions：提供方说明的数组，应在显示搜索结果时显示。数组中的每个条目都包含一条提供方说明的 HTML 文本。注意：这是整个搜索响应的所有提供方说明的集合。因此，响应中的所有 PlaceResult 对象均包含相同的提供方说明列表。
  • icon 会返回 71 像素 x 71 像素的 PNG 彩色图标的网址。
  • icon_mask_base_uri 会返回非彩色图标（去掉 .svg 或 .png 扩展名）的基准网址。
  • icon_background_color 会返回地点类别的默认十六进制颜色码。
  • name：地点的名称。
  • opening_hours 可能包含以下信息：
    • open_now 是一个布尔值，表示地点当前是否正在营业（在 Maps JavaScript API 地点库中已弃用，建议改用 utc_offset_minutes）。
  • place_id 是用于唯一标识地点的文本标识符。如需检索地点的相关信息，请在“地点详情”请求中传递此标识符。详细了解如何通过地点 ID 引用地点。
  • rating 包含根据用户总体评价得出的地点评分（从 0.0 到 5.0）。
  • types：此地点的类型数组（例如，["political", "locality"] 或 ["restaurant", "lodging"]）。此数组可以包含多个值，也可以为空。我们可能会在未事先通知您的情况下引入新值。请参阅支持的类型列表。
  • vicinity：地点的简化地址，包括街道名称、门牌号和市行政区，但不包括省/州、邮政编码或国家/地区。例如，Google 澳大利亚悉尼办事处的 vicinity 值为 5/48 Pirrama Road, Pyrmont。

访问其他结果

默认情况下，对于每个地点搜索，每次查询可返回最多 20 条结果。但是，每个搜索可以返回多达 60 条结果，分三页显示。可以通过 PlaceSearchPagination 对象获取其他页面。为了访问其他页面，您必须通过一个回调函数获取 PlaceSearchPagination 对象。PlaceSearchPagination 对象的定义如下：

  • hasNextPage 是一个布尔值属性，表示是否还有其他结果。如果存在额外的结果页面，属性值为 true。
  • nextPage() 是一个函数，可返回下一组结果。在执行搜索后，您必须等待两秒钟，才会显示下一页结果。

若要查看下一组结果，请调用 nextPage。系统必须先显示当前页面的结果，然后才能显示下一页的结果。请注意，每次搜索都算作用量限额中的一次请求。

以下示例演示了如何更改回调函数来捕获 PlaceSearchPagination 对象，以便您发出多个搜索请求。

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
查看示例

试用示例

地点详情

除了提供某个区域内的地点列表，地点服务还可以返回有关特定地点的详细信息。当地点搜索响应中返回某个地点后，可以使用其地点 ID 请求有关该地点的更多详细信息，例如完整地址、电话号码、用户评分和评价等。

“地点详情”请求

您可以调用服务的 getDetails() 方法发出“地点详情”请求。

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

此方法会发出包含以下内容的请求：所需地点的 placeId，以及用于表示要返回哪些类型的地点数据的字段。详细了解如何通过地点 ID 引用地点。

该方法还采用了回调方法，这需要处理传入 google.maps.places.PlacesServiceStatus 响应的状态代码以及 google.maps.places.PlaceResult 对象。

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

查看示例

字段（地点详情）

fields 参数需要采用字符串数组（字段名称）。

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

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

基本

“基本”类别包括以下字段：
address_components、adr_address、business_status、formatted_address、geometry、icon、icon_mask_base_uri、icon_background_color、name、permanently_closed（已弃用）、photo、place_id、plus_code、type、url、utc_offset（在 Maps JavaScript API 地点库中已弃用）、utc_offset_minutes、vicinity

联系人

“联系人”类别包括以下字段：
formatted_phone_number、international_phone_number、opening_hours、website

氛围

“氛围”类别包括以下字段：price_level、rating、reviews、user_ratings_total

详细了解地点字段。如需详细了解地点数据请求的结算方式，请参阅用量和结算。

“地点详情”响应

状态代码

PlacesServiceStatus 响应对象包含请求的状态，可能还包含调试信息，以帮助您跟踪“地点详情”请求失败的原因。可能的状态值包括：

  • INVALID_REQUEST：该请求无效。
  • OK：响应中包含有效的结果。
  • OVER_QUERY_LIMIT：网页已超出其请求配额。
  • NOT_FOUND：地点数据库中未找到引用的位置。
  • REQUEST_DENIED：不允许网页使用 PlacesService。
  • UNKNOWN_ERROR：由于服务器错误，无法处理 PlacesService 请求。如果您重试一次，请求可能会成功。
  • ZERO_RESULTS：找不到关于此请求的任何结果。

“地点详情”结果

成功的 getDetails() 调用会返回 PlaceResult 对象，其中包含以下属性：

  • address_components：包含适用于该地址的各个组成部分的数组。

    每个地址组成部分通常包含以下字段：

    • types[] 是一个数组，表示地址组成部分的类型。请参阅支持的类型列表。
    • long_name 是地理编码器返回的地址组成部分的完整文本说明或名称。
    • short_name 是地址组成部分的缩写文本名称（如果有）。例如，阿拉斯加州的地址组成部分可能包含 long_name“Alaska”和 short_name“AK”（使用 2 个字母的邮编缩写）。

    address_components[] 数组的注意事项如下：

    • 地址组成部分的数组包含的组成部分可能多于 formatted_address。
    • 除了 formatted_address 中包含的政治实体之外，数组不一定会纳入包含地址的所有政治实体。若要检索包含特定地址的所有政治实体，您应使用反向地理编码，并将地址的纬度/经度作为参数传递给请求。
    • 两次请求之间的响应格式不一定相同。特别是，address_components 的数量因所请求的地址而异，对于同一个地址，数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组成部分。
  • business_status 表示地点的营业状态（如果该地点为商家）。它可以包含以下其中一个值：
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    如果不存在任何数据，将不会返回 business_status。
  • formatted_address：此地点直观易懂的地址。

    此地址通常相当于邮政地址。请注意，由于许可限制，某些国家/地区（例如英国）不允许发布真实的邮政地址。

    设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如，地址“111 8th Avenue, New York, NY”包含以下组成部分：“111”（门牌号）、“8th Avenue”（道路名称）、“New York”（城市）和“NY”（美国州名）。

    请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分，API 响应除了包含设有格式的地址字段外，还包含这些组成部分。

  • formatted_phone_number：地点的电话号码，其格式遵循号码的地区惯例。
  • geometry：地点的几何图形相关信息。其中包括：
    • location 提供该地点的纬度和经度。
    • viewport 定义查看该地点时地图上的首选视口。
  • permanently_closed（已弃用）是一个布尔值标记，表示该地点是已永久停业还是暂时停业（值为 true）。请勿使用 permanently_closed，建议改用 business_status 来获取商家的营业状态。
  • plus_code（请参阅 Open Location Code 和 Plus Codes）是经过编码的位置引用，衍生自纬度和经度坐标，表示面积不超过 1/8,000 度 x 1/8,000 度（在赤道处约为 14 米 x 14 米）的区域。Plus Codes 可用于在没有街道地址的地点（例如建筑物未编号，或者街道未命名）取代街道地址。

    Plus Code 的格式包括全局代码和混合代码：

    • global_code 是包含 4 个字符的区号和至少包含 6 个字符的区域代码 (849VCWC8+R9)。
    • compound_code 是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9, Mountain View, CA, USA）。请勿以程序化方式解析此内容。
    通常情况下，系统会返回全局代码和混合代码。但是，如果结果是在偏远位置（例如海洋或沙漠），系统可能只会返回全局代码。
  • html_attributions：要针对此地点结果显示的提供方说明文本。
  • icon：指向可用于代表该地点类型的图片资源的网址。
  • international_phone_number 包含地点的电话号码（采用国际电话号码格式）。国际电话号码格式包含国家/地区代码，并且带有一个加号 (+) 前缀。例如，Google 澳大利亚悉尼办事处的 international_phone_number 为 +61 2 9374 4000。
  • name：地点的名称。
  • utc_offset 在 Maps JavaScript API 地点库中已弃用，建议改用 utc_offset_minutes。
  • utc_offset_minutes 包含此地点当前时区偏离世界协调时间 (UTC) 的分钟数。例如，对于澳大利亚悉尼的地点，在夏令时期间，该值为 660（偏离 UTC +11 小时），对于加利福尼亚州的地点，在非夏令时期间，该值为 -480（偏离 UTC -8 小时）。
  • opening_hours 包含以下信息：
    • open_now 在 Maps JavaScript API 地点库中已弃用；建议改用 opening_hours.isOpen()。请观看此视频，了解如何将 isOpen 与“地点详情”搭配使用。这是一个布尔值，表示该地点当前是否正在营业。
    • periods[] 是一个涵盖七天的营业时段数组，从星期日开始，按时间顺序排列。每个时段均包含：
      • open 包含一对日期和时间对象，用于说明该地点的营业时段：
        • day 是一个介于 0 到 6 之间的数字，对应于星期几（从星期日开始）。例如，2 表示星期二。
        • time 可能包含一天中的某个时段，采用 24 小时制 hhmm 格式（值的范围为 0000 - 2359）。系统将按地点的时区报告 time。
      • close 可能包含一对日期和时间对象，用于说明该地点的休息时段。注意：如果某个地点全天营业，响应中将缺少 close 部分。应用可以通过以下方式表示全天营业：将 open 中的 day 设置为 0，将 time 设置为 0000，并且不包含 close。
    • weekday_text 是包含七个字符串的数组，用于以特定格式表示一周内每天的营业时间。如果“地点详情”请求中指定了 language 参数，地点服务会根据该语言设置营业时间格式，并进行本地化。此数组中元素的顺序取决于 language 参数。有些语言以星期一作为一周的开始，有些语言则以星期日作为开始。
  • permanently_closed（已弃用）是一个布尔值标记，表示该地点是已永久停业还是暂时停业（值为 true）。请勿使用 permanently_closed，建议改用 business_status 来获取商家的营业状态。
  • photos[]：PlacePhoto 对象的数组。您可以使用 PlacePhoto 通过 getUrl() 方法来获取照片，也可以检查对象是否包含以下值：
    • height：图片的最大高度，以像素为单位。
    • width：图片的最大宽度，以像素为单位。
    • html_attributions：要随此地点照片一起显示的提供方说明文本。
  • place_id：一个文本标识符，用于唯一标识某个地点，并可用于通过“地点详情”请求检索该地点的相关信息。详细了解如何通过地点 ID 引用地点。
  • rating：根据用户总体评价得出的地点评分（从 0.0 到 5.0）。
  • reviews：一个最多包含五条评价的数组。每条评价均包含几个组成部分：
    • aspects[] 包含一个 PlaceAspectRating 对象数组，其中每个对象都提供对该场所单个属性的评分。该数组中的第一个对象被视为主要评分指标。每个 PlaceAspectRating 的定义如下：
      • type：表示评分指标名称。支持以下类型：appeal、atmosphere、decor、facilities、food、overall、quality 和 service。
      • rating：表示用户针对该特定评分指标的评分，范围为 0 至 3。
    • author_name：表示提交评价的用户的姓名。匿名评价的作者统称为“Google 用户”。如果设置了语言参数，“Google 用户”词组将返回一个经过本地化的字符串。
    • author_url：表示指向用户 Google+ 个人资料（如果有的话）的网址。
    • language：表示用户评价所用语言的 IETF 语言代码。此字段仅包含主要语言标记，而不包含表示国家或地区的辅助标记。例如，所有英语评价都标记为“en”，而不是“en-AU”或“en-UK”等。
    • rating：表示用户对此地点的总体评分。这是一个整数，范围为 1 至 5。
    • text：表示用户的评价。通过 Google 地点评价某个位置时，文本评价被视为可选项；因此，此字段可能为空。
  • types：此地点的类型数组（例如，["political", "locality"] 或 ["restaurant", "lodging"]）。此数组可以包含多个值，也可以为空。我们可能会在未事先通知您的情况下引入新值。请参阅支持的类型列表。
  • url：此地点的官方 Google 页面的网址。这是由 Google 拥有的页面，其中包含有关该地点的实用信息。在任何向用户显示该地点详细结果的屏幕上，应用必须提供页面链接或者嵌入此页面。
  • vicinity：地点的简化地址，包括街道名称、门牌号和市行政区，但不包括省/州、邮政编码或国家/地区。例如，Google 澳大利亚悉尼办事处的 vicinity 值为 5/48 Pirrama Road, Pyrmont。系统仅会针对附近搜索返回 vicinity 属性。
  • website：用于列出此地点的官方网站，例如商家主页。

注意：并非所有地点都可使用多维评分。如果评价太少，详情响应可能包含一个 0.0 至 5.0 之间的旧版评分（如果可用），也可能不包含任何评分。

通过地点 ID 引用地点

地点 ID 是对 Google 地图上地点的唯一引用。地点 ID 适用于大多数位置，包括商家、地标、公园和交叉路口。

若要在您的应用中使用地点 ID，您必须先查找该 ID，它可以在“地点搜索”请求或“地点详情”请求的 PlaceResult 中找到。然后，您可以使用此地点 ID 来查找地点详情。

地点 ID 不受 Google Maps Platform 服务条款第 3.2.3(b) 条中规定的缓存限制的约束。因此，您可以存储地点 ID 值以供日后使用。如需了解存储地点 ID 的最佳实践，请参阅地点 ID 概览。

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

地点照片

您可以通过 Place Photo 功能在自己的网站上添加高品质照片内容。借助照片服务，您可以访问存储在地点数据库和 Google+ 本地数据库中的数百万张照片。当您使用“地点详情”请求获取地点信息时，系统将返回相关照片内容的照片引用。“附近搜索”和“文本搜索”请求也会为每个地点返回一个照片引用（如果相关）。使用照片服务，您可以访问所引用的照片，并根据自己的应用将图片调整为最适合的大小。

对于针对 PlacesService 发出的任何 getDetails()、textSearch() 或 nearbySearch() 请求，系统会返回 PlacePhoto 对象数组，作为 PlaceResult 对象的一部分。

注意：返回的照片数量因请求而异。

  • “附近搜索”或“文本搜索”最多会返回一个 PlacePhoto 对象。
  • “地点详情”请求最多会返回十个 PlacePhoto 对象。

您可以通过调用 PlacePhoto.getUrl() 方法并传入一个有效的 PhotoOptions 对象来请求关联图片的网址。PhotoOptions 对象允许您指定图片所需的最大高度和宽度。如果您同时为 maxHeight 和 maxWidth 指定值，照片服务会将图片大小调整为两种尺寸中的较小者，同时保留原始宽高比。

以下代码段会接受地点对象，如果存在照片，还会向地图添加标记。默认的标记图片将替换为缩略版照片。

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

照片服务返回的照片来自各种位置，包括商家和用户贡献的照片。在大多数情况下，使用这些照片时可以不包含提供方说明，或者可以在图片中显示必要的提供方说明。但是，如果返回的 photo 元素在 html_attributions 字段中包含值，无论您在哪里显示相应图片，都要在应用中包含额外的提供方说明。