地点库

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
选择平台Android iOS JavaScript Web 服务

概览

Places Library 和 Maps JavaScript API 中的函数可让您的应用搜索已定义区域(例如地图边界)或固定地点周围的地点(在此 API 中定义为场所、地理位置或著名地图注点)。

Places API 提供自动补全功能,您可以使用该功能为您的应用提供 Google 地图搜索字段的提前输入搜索行为。当用户开始输入地址时,自动补全功能就会填充该地址的其余部分。如需了解详情,请参阅自动补全文档

开始使用

如果您不熟悉 Maps JavaScript API 或 JavaScript,我们建议您先查看 JavaScript 并获取 API 密钥,然后再开始使用。

启用 API

在使用 Maps JavaScript API 中的 Places 库之前,请先确保在 Google Cloud Console 中针对您为 Maps JavaScript API 设置的项目中启用了 Places API。

要查看已启用 API 的列表,请执行以下操作:

  1. 转到 Google Cloud Console
  2. 点击选择项目按钮,然后选择您为 Maps JavaScript API 设置的同一项目,然后点击打开
  3. 信息中心的 API 列表中,查找 Places API
  4. 如果您在列表中看到 Places API,则说明该 API 已启用。如果列出该 API,请启用它:
    1. 在页面顶部,选择启用 API 和服务以显示标签页。或从左侧菜单中选择
    2. 搜索 Places API,然后从结果列表中选择它。
    3. 选择启用。该过程完成后,Places API 会显示在信息中心的 API 列表中。

加载库

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

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

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

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

对密钥应用 API 限制后,只有一个或多个 API 或 SDK 可以使用 API 密钥。系统会处理对与 API 密钥关联的 API 或 SDK 的请求。向未与 API 密钥关联的 API 或 SDK 发出的请求将失败。 如需限制与 Places Library 和 Maps JavaScript API 配合使用的 API 密钥,请执行以下操作:
  1. 转到 Google Cloud Console
  2. 点击项目下拉菜单,选择包含您要保护的 API 密钥的项目。
  3. 点击菜单按钮 ,然后选择 Google Maps Platform &Credentials
  4. 凭据页面上,点击要保护的 API 密钥的名称。
  5. 限制和重命名 API 密钥页面上,设置限制:
    • API 限制
      • 选择限制密钥
      • 点击选择 API,然后选择 Maps JavaScript APIPlaces API
        (如果其中任一 API 未列出,您需要启用它。)
  6. 点击保存

使用限额和政策

配额

Places Library 和 JavaScript API 与 Places API 共用使用配额(如 Places API 使用限制文档中所述)。无论多少用户共享同一项目,每秒查询数的限额都应用到每个用户的会话中。*

注意:首次加载 API 时,系统会为您分配初始请求配额。您使用此配额后,该 API 会对每秒的请求施加速率限制。如果您在特定时间段内发出的请求过多,API 会返回 OVER_QUERY_LIMIT 响应代码。基于会话的速率限制可防止将客户端服务用于批量请求。对于批量请求,请使用我们的网络服务 API。

政策

使用 Places Library、Maps JavaScript API 时,必须遵守针对 Places API 所述的政策

地点搜索

借助地点服务,您可以进行以下类型的搜索:

返回的信息可能包括餐厅、商店和办公室等场所,以及地理编码结果(表示地址、城镇和城市等政治区域)以及其他地图注点。

查找地点请求

通过“查找地点”请求,您可以通过文本查询或电话号码来搜索地点。“查找地点”请求分为两种类型:

通过查询查找地点

从查询中查找地点会接受文本输入并返回地点。输入可以是任何类型的地点数据,例如商家名称或地址。如需发出从查询中查找地点的请求,请调用 PlaceServicefindPlaceFromQuery() 方法,该方法采用以下参数:

  • query(必需)要搜索的文本字符串,例如“餐馆”或“大街 123 号”。此值必须是场所名称、地址或场所类别。任何其他类型的输入都可能产生错误,并且不能保证返回有效结果。Places API 将根据此字符串返回候选匹配项,并按照感知的相关程度对结果进行排序。
  • fields(必需)一个或多个指定要返回的地点数据类型的字段
  • locationBias(可选)用于定义搜索区域的坐标。可能是以下某一项:

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

以下示例显示了对 findPlaceFromQuery() 的调用,搜索“澳大利亚当代艺术博物馆”,并包含 namegeometry 字段。

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);
    }
  });
}
查看示例

根据电话号码查找地点

根据电话号码查找地点:获取电话号码并返回地点。如需发出“从电话号码查找地点”请求,请调用 PlaceServicefindPlaceFromPhoneNumber() 方法,该方法采用以下参数:

  • phoneNumber(必需)电话号码,采用 E.164 格式。
  • fields(必需)一个或多个指定要返回的地点数据类型的字段
  • locationBias(可选)用于定义搜索区域的坐标。可能是以下某一项:

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

字段(查找地点方法)

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

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

基本版

“基本”类别包括以下字段:
business_statusformatted_addressgeometryiconicon_mask_base_uriicon_background_colornamepermanently_closed已弃用)、photosplace_idplus_codetypes

联系人

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

氛围

“氛围”类别包括以下字段: price_levelratinguser_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 对象)和半径(以米为单位)。

通过调用 PlacesServicenearbySearch() 方法可启动“附近地点”搜索,该方法会返回一组 PlaceResult 对象。请注意,从版本 3.9 开始,nearbySearch() 方法会替换 search() 方法。

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

此方法发出的请求中包含以下字段:

  • 以下任一选项:
    • bounds,它必须是定义矩形搜索区域的 google.maps.LatLngBounds 对象;或者
    • locationradius;前者接受 google.maps.LatLng 对象,后者接受简单的整数,表示圆形的半径(以米为单位)。允许的最大半径为 50000 米。请注意,当 rankBy 设置为 DISTANCE 时,您必须指定 location,但不能指定 radiusbounds
  • keyword(可选)- 要与所有可用字段匹配的字词,包括但不限于名称、类型和地址,以及客户评价和其他第三方内容。
  • minPriceLevelmaxPriceLevel(可选)- 将结果限制为指定范围内的地点。有效值介于 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,则需要 keywordnametype 中的一个或多个。
  • 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 地点文本搜索服务是一项网络服务,可根据字符串(例如“北京的烤鸭店”或“渥太华附近的鞋店”)返回一组地点的相关信息。该服务返回与文本字符串匹配的地点列表以及已设置的任何地点偏向作为响应。搜索响应将包含地点列表。您可以发送“地点详情”请求,以详细了解响应中的任何地点。

您可通过调用 PlacesServicetextSearch() 方法来启动文本搜索。

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

此方法发出的请求中包含以下字段:

  • query(必需)要搜索的文本字符串,例如“餐馆”或“123 主街 123 号”。此值必须是场所名称、地址或场所类别。任何其他类型的输入都可能产生错误,并且不能保证返回有效结果。地点服务将根据此字符串返回候选匹配项,并按照结果的相关程度对其进行排序。如果搜索请求中也使用了 type 参数,此参数会变为可选参数。
  • (可选)
    • openNow - 布尔值,指明“地点”服务应仅返回发送查询时正在营业的地点。如果您在查询中包含此参数,就不会返回未在 Google 商家信息数据库中指定营业时间的地点。将 openNow 设置为 false 不会产生任何影响。
    • minPriceLevelmaxPriceLevel - 将结果限制为指定价格水平内的地点。有效值介于 0(最实惠)和 4(最昂贵)之间,包含 0 和 4。
    • 以下任一选项:
      • bounds - 定义作为搜索范围的矩形的 google.maps.LatLngBounds 对象;或
      • locationradius - 您可以通过传递 locationradius 参数,使结果偏向指定圆形。这将指示地点服务优先显示此范围内的结果。定义区域以外的结果可能仍会显示。 位置采用 google.maps.LatLng 对象,半径采用简单的整数,表示圆形的半径(以米为单位)。所允许的最大半径为 50000 米。
    • 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”包含以下组成部分:&q 111”(街道号码)、“8th Avenue”(城市)、“NY”(纽约市)和“NY”(美国的一个州)。

    请勿以编程方式解析格式化的地址。相反,除了 API 格式的地址字段之外,您还应使用 API 响应包含的各个地址组成部分。

  • geometry:地点的几何图形相关信息。其中包括:
    • location 提供地点的纬度和经度。
    • viewport 定义在查看该地点时地图上的首选视口。
  • permanently_closed(已弃用)是一个布尔值标志,指示该地点已永久关闭还是暂时关闭(值为 true)。请勿使用 permanently_closed请改用 business_status 获取商家的运营状态。
  • plus_code(请参阅打开位置代码 Plus 代码)是基于纬度和经度坐标推导的编码位置引用,表示面积:1/8000 度、1/8000 度(赤道约 14 米 x 14 米)。Plus 代码可用于替换不存在的地点(建筑物没有编号或街道未命名)中的街道地址。

    Plus 代码采用全局代码和复合代码格式:

    • global_code 是包含 4 个字符的区号和至少 6 个字符的当地代码 (849VCWC8+R9)。
    • compound_code 是包含 6 个字符或更长时间的本地代码,具有明确位置(CWC8+R9,Mountain View, CA, USA)。请勿以编程方式解析此内容。
    通常,系统会同时返回全局代码和复合代码。但是,如果结果位于偏远地区(例如海洋或沙漠),系统可能只会返回全局代码。
  • html_attributions:显示搜索结果时应显示的归因数组。该数组中的每个条目都包含单个提供方说明的 HTML 文本。注意:这是整个搜索响应的所有归因的集合。因此,响应中的所有 PlaceResult 对象都包含相同的归因列表。
  • icon 会返回彩色 71px x 71px PNG 图标的网址。
  • icon_mask_base_uri 会返回一个无色图标的基准网址,减去 .svg 或 .png 扩展名。
  • icon_background_color 会返回地点类别的默认十六进制颜色码。
  • name:地点的名称。
  • opening_hours 可能包含以下信息:
    • open_now 是一个布尔值,指示地点目前是否处于打开状态(在 Places Library 和 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;

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;
查看示例

试用示例

地点详情

除了提供某个区域内的地点列表外,地点服务还可以返回特定地点的详细信息。在地点搜索响应中返回某个地点后,可以使用其地点 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_component', 'opening_hours', 'geometry']。指定复合值时,请使用英文句点。例如:opening_hours.weekday_text

这些字段与地点详情结果相对应,分为三个结算类别:基本、联系人和氛围。基本字段采用基本费率计费,不会产生额外费用。“联系人”和“氛围”字段以较高费率结算。如需了解详情,请参阅价格表。无论是否调用,归因都会始终随每次调用返回归因 (html_attributions)。

基本版

“基本”类别包括以下字段:
address_componentadr_addressbusiness_statusformatted_addressgeometryiconicon_mask_base_uriicon_background_colornamepermanently_closed已弃用)、photoplace_idplus_codetypeurlutc_offset、Maps 2)adr_address

联系人

“联系人”类别包括以下字段:
formatted_phone_numberinternational_phone_numberopening_hourswebsite

氛围

“氛围”类别包括以下字段: price_levelratingreviewuser_ratings_total

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

地点详情响应

状态代码

PlacesServiceStatus 响应对象包含请求的状态,并且可能会包含调试信息,以帮助您找到地点详情请求失败的原因。可能的状态值为:

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

地点详情结果

成功的 getDetails() 调用会返回具有以下属性的 PlaceResult 对象:

  • address_components:一个数组,包含适用于该地址的单独组件。

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

    • types[] 是一个数组,表示地址组成部分的类型。请参阅支持的类型列表。
    • long_name 是地址解析器返回的完整文本说明或地址组成部分的名称。
    • short_name 是地址组成部分的缩写文本名称(如果有)。例如,阿拉斯加州的地址组成部分可能具有“阿拉斯加”的 long_nameshort_name 为“AK”的双字母邮政缩写。

    请注意关于 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”包含以下组成部分:&q 111”(街道号码)、“8th Avenue”(城市)、“NY”(纽约市)和“NY”(美国的一个州)。

    请勿以编程方式解析格式化的地址。相反,除了 API 格式的地址字段之外,您还应使用 API 响应包含的各个地址组成部分。

  • formatted_phone_number:地点的电话号码,格式遵循号码区域惯例
  • geometry:地点的几何图形相关信息。其中包括:
    • location 提供地点的纬度和经度。
    • viewport 定义在查看该地点时地图上的首选视口。
  • permanently_closed(已弃用)是一个布尔值标志,指示该地点已永久关闭还是暂时关闭(值为 true)。请勿使用 permanently_closed请改用 business_status 获取商家的运营状态。
  • plus_code(请参阅打开位置代码 Plus 代码)是基于纬度和经度坐标推导的编码位置引用,表示面积:1/8000 度、1/8000 度(赤道约 14 米 x 14 米)。Plus 代码可用于替换不存在的地点(建筑物没有编号或街道未命名)中的街道地址。

    Plus 代码采用全局代码和复合代码格式:

    • 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 Places Library 和 Maps JavaScript API 中已弃用,请改用 utc_offset_minutes
  • utc_offset_minutes 包含此地点当前时区与世界协调时间 (UTC) 的分钟数。例如,对于澳大利亚夏令时间的夏令时,此值将为 660(世界协调时间为 +11 小时);而对于夏令时以外,加利福尼亚的地点则为 -480(世界协调时间为 -8 小时)。
  • opening_hours 包含以下信息:
    • open_now(在 Maps JavaScript API 地点库中的已弃用;请改用 opening_hours.isOpen())。请参阅此视频了解如何将 isOpen 与地点详情结合使用。)是一个布尔值,指示该地点当前是否营业。
    • periods[] 是一个从星期日开始的 7 天开始时间段数组(按时间顺序排列)。每个时间段均包含:
      • open 包含一对日期和时间对象,用于描述该地点的营业时间:
        • day 是一个介于 0 到 6 之间的数字,对应于从星期日开始的一周中的某几天。例如,2 表示星期二。
        • time 可以包含 24 小时制时间格式的时间值(值的范围为 0000–2359)。系统会按照该地点的时区报告 time
      • close 可以包含一对日期和时间对象,用于描述该地点的营业时间。注意:如果地点始终营业,响应中将缺少 close 部分。应用可以依赖 open 时间段(包含值为 0 的 day 和值为 0000 的 time,而不包含 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:最多包含 5 条评价的数组。每条评价都由几部分组成:
    • aspects[] 包含 PlaceAspectRating 对象的数组,其中每个对象都提供对场所的单个属性的评分。数组中的第一个对象被认为是主要方面。每个 PlaceAspectRating 的定义如下:
      • type 被评分的方面的名称。支持以下类型:appealatmospheredecorfacilitiesfoodoverallqualityservice
      • 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 查找地点详情

地点 ID 不受 Google Maps Platform 服务条款第 3.2.3(a) 条中所述的缓存限制的约束。因此,您可以存储地点 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);

地点照片

通过“地点照片”功能,您可以为自己的网站添加高品质的摄影内容。通过照片服务,您可以访问 Places 和 Google+ Local 数据库中存储的数百万张照片。当您使用“地点详情”请求获取地点信息时,系统会返回相关照片内容的照片引用。“附近搜索”和“文本搜索”请求也会为每个地点返回单个照片引用(如相关)。然后,您可以使用照片服务访问引用的照片,并将图片调整为适合您的应用的大小。

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

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

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

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

以下代码段可接受地点对象,并在照片存在时向地图添加标记。默认标记图片会被替换为小版照片。

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 字段中包含值,则无论在何处显示图片,您都必须在应用中添加额外的提供方信息。