一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Places API Web Service

为帮助您起步,我们将引导您在 Google 开发者控制台中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Places API Web Service
  3. 创建相应密钥
继续

地点自动完成

地点自动完成服务是一项 Web 服务,可在 HTTP 请求的响应中返回预测地点。该请求指定文本搜索字符串和地理边界(可选)。此服务可将商家、地址和景点等地点作为用户类型返回,因此,可为基于文本的地理搜索提供自动完成功能。

地点自动完成请求

地点自动完成服务是 Google Places API Web Service 的一部分,与 Google Places API Web Service 共享 API 密钥和配额。

地点自动完成服务可以匹配完整的字词及子字符串,因此,应用可将查询作为用户类型发送,以提供实时的预测地点。

系统会向用户显示返回的预测地点,以帮助他们选择所需的地点。您可以发送地点详情请求,了解所返回地点的详情。

地点自动完成请求是一个 HTTP URL,其格式如下:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

其中,output 可以是以下值之一:

  • json(推荐)指示以 JavaScript 对象标记 (JSON) 输出
  • xml 指示以 XML 格式输出

您需要使用特定的参数,才能发起地点自动完成请求。依照 URL 的标准,所有参数都使用“与”字符 (&) 分隔。下面枚举了各个参数及其可能的值。

必填参数

  • input – 要搜索的文本字符串。地点自动完成服务将根据此字符串返回候选匹配项,并按照其判断的相关程度对结果排序。
  • key – 您的应用的 API 密钥。此密钥可以标识您的应用,以便进行配额管理。请参阅获取密钥了解更多信息。Google Maps APIs Premium Plan 客户必须使用作为 Premium Plan 购买项的一部分为其创建的 API 项目。

可选参数

  • offset – 服务执行预测匹配时所使用的最后一个字符在输入字词中的位置。例如,如果输入为“Google”,offset 为 3,则服务将匹配“Goo”。由 offset 确定的字符串仅匹配输入字词中的第一个字词。例如,如果输入字词为“Google abc”,offset 为 3,则服务将尝试匹配“Goo abc”。若未提供 offset,该服务将使用整个字词。offset 一般应设置为文本插入符的位置。
  • location – 您想要检索地点信息的地点。必须指定为“纬度,经度”形式。
  • radius – 返回地点结果的范围(以米为单位)。请注意,设置 radius 会使结果偏向指定区域,但无法将结果完全限制于指定区域内。请参阅下面的位置偏向位置限制
  • language – 语言代码,表示返回结果所应使用的语言(如提供该语言的话)。搜索功能同样偏向于所选的语言;使用所选语言的结果排名更高。请参阅支持的语言列表及其代码。请注意,我们会经常更新支持的语言,因此,此列表可能并不全面。若未提供语言,地点自动完成服务将尝试使用发送请求区域的本地语言。
  • types – 返回的地点结果的类型。请参阅下面的地点类型。若未指定类型,将返回所有类型。
  • components – 用于限定结果范围的地点分组。目前,您可以使用 components 按国家/地区过滤。国家/地区必须以兼容 ISO 3166-1 Alpha-2 的双字符国家/地区代码传递。例如:components=country:fr 会将结果限制为在法国境内的地点。
  • strictbounds - 仅返回由 locationradius 定义的区域内的地点。这是一种限制(而非偏向),表示即使此区域以外的结果与用户输入匹配,也不会返回这些结果。

位置偏向

通过传递 locationradius 参数,可以使结果偏向指定的圆形区域内。这会指示地点自动完成服务优先显示该区域内的结果,定义区域以外的结果也会显示。您可以使用 components 参数过滤结果,以便仅显示指定国家/地区境内的地点。

提示:搜索区域较大时,场所结果的排名通常会较低,因而不会显示在结果中。如果您希望场所出现在场所/地理代码的混合结果中,可以指定较小的半径。或者,也可使用 types=establishment 将结果限制为仅显示场所。

地点限制

您还可以通过添加 strictbounds 参数,将结果限制到由 locationradius 参数定义的区域。这会指示地点自动填充服务返回该区域内的结果。

地点类型

您可以通过传递 types 参数将地点自动完成请求的结果限制为特定类型。该参数指定为某种类型或某个类型集合,支持的类型详见下文。若未指定任何类型,系统将返回所有类型。一般仅允许指定一种类型。例外情况是您可以安全地混用 geocodeestablishment 类型,但是请注意,这样做的效果等同于未指定类型。支持的类型为:

  • geocode:指示“地点自动完成”服务仅返回地理编码结果,而不是返回商家结果。通常,此请求可用来消除模棱两可的结果,也就是指定位置可能不明确的结果。
  • address:指示“地点自动完成”服务仅返回具有精确地址的地理编码结果。通常,当您知道用户要查找的是完全确定的地址时,推荐使用此请求。
  • establishment:指示“地点自动完成”服务仅返回商家结果。
  • (regions) 类型集合:指示“地点”服务返回匹配以下类型的任意结果:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • (cities) 类型集合:指示“地点”服务返回匹配 localityadministrative_area_level_3 的结果。

自动完成请求示例

在以加利福尼亚旧金山为中心的区域内请求包含字符串“Amoeba”的场所:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

相同的请求,限制为旧金山 Ashbury St 和 Haight St 周围 500 米内的结果:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

请求包含“Vict”的地址,并以法语显示结果:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY

请求包含“Vict”的城市,并以巴西葡萄牙语显示结果:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY

请注意,您需要将这些示例中的 API 密钥替换成您自己的密钥。

地点自动完成响应

地点自动完成响应的返回格式通过请求 URL 路径中的 output 标志指定。下面是通过以下参数查询所返回的结果:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

JSON 响应包含以下两个根元素:

  • status 包含请求的元数据。请参阅下面的状态代码
  • predictions 包含一个地点数组,其中包含该地点的相关信息。有关这些结果的详情,请参阅地点自动完成结果。Google Places API Web Service 最多返回 5 个结果。

这些结果中尤其值得关注的是 place_id 元素,该元素可用于通过单独的查询请求更详尽的地点。请参阅地点详情请求

请参阅使用 Javascript 处理 JSON,了解如何解析 JSON 响应。

XML 响应包含一个 <AutocompletionResponse> 元素和以下两种类型的子元素:

  • 单个 <status> 元素包含相关请求的元数据。请参阅下面的状态代码
  • <prediction> 元素(零个或多个),每个此类元素都包含某个地点的相关信息。有关这些结果的详情,请参阅地点自动完成结果。Google Places API Web Service 最多返回 5 个结果。

除非出于某些原因,您的应用要求使用 xml,否则我们推荐您使用 json 作为首选输出标志。处理 XML 树时应小心谨慎,以便引用正确的节点和元素。请参阅使用 XPath 解析 XML,了解如何处理 XML。

状态代码

地点自动完成响应对象中的 status 字段包含请求的状态,还可包含调试信息,以帮助您查出地点自动完成请求失败的原因。status 字段可以包含以下值:

  • OK 表示未出现错误,并且至少返回一个结果。
  • ZERO_RESULTS 表示搜索成功,但未返回任何结果。如果搜索中传递了一个偏远位置的 bounds,可能会出现此状态。
  • OVER_QUERY_LIMIT 表示您已超出配额。
  • REQUEST_DENIED 表示系统已拒绝您的请求,这通常是因为缺少有效的 key 参数。
  • INVALID_REQUEST 通常表示缺少 input 参数。

错误消息

当“地点”服务返回 OK 以外的状态代码时,在响应对象中可能会包含附加的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

地点自动完成结果

“地点”服务返回搜索到的 JSON 结果时,会将这些结果放在 predictions 数组中。即使该服务没有返回结果(例如 location 比较偏远),它仍然会返回一个空的 predictions 数组。XML 响应包含零个或多个 <prediction> 元素。

每个预测结果均包含以下字段:

  • description 包含返回结果的可人工读取名称。对于 establishment 结果,这通常是指商家名称。
  • place_id 是用于唯一标识地点的文本标识符。要检索有关该地点的信息,请在 Google Places API Web Service 请求的 placeId 字段中传递此标识符。如需了解有关地点 ID 的详细信息,请参阅地点 ID 概览
  • reference 包含一个唯一的令牌,可用于在地点详情请求中检索有关此地点的附加信息。尽管此令牌唯一标识该地点,但是反之则不然。一个地点可以有多个有效的引用令牌。对于任何给定的地点,系统无法保证在不同的搜索中会返回相同的令牌。reference 已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
  • id 包含指示此地点的唯一稳定标识符。此标识符可能无法用于检索有关此地点的信息,但是可用于合并有关此地点的数据,并在不同的搜索中验证地点的同一性。id 已被弃用,取而代之的是 place_id。请参阅此页的弃用通告
  • terms 包含一个字词数组,用于标识所返回说明的各个部分(说明的各部分通常以逗号结尾)。数组中的每个条目均具有 value 字段(它包含字词文本)和 offset 字段(用于定义相应字词在说明中的起始位置,以 Unicode 字符数表示)。
  • types 包含适用于此地点的类型数组。例如:[ "political", "locality" ][ "establishment", "geocode" ]
  • matched_substrings 包含的数组具有 offset 值和 length。这些字段说明输入的字词在预测结果文本中的位置,以便根据需要突出显示该字词。

sensor 参数

Google Places API Web Service 之前要求您包括 sensor 参数,以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。

发送以下问题的反馈:

此网页
location_on
Google Places API Web Service