地点自动补全（旧版）

欧洲经济区 (EEA) 开发者

地点自动补全（旧版）是一项 Web 服务，可针对 HTTP 请求返回地点预测结果。该请求指定了文本搜索字符串和可选的地理边界。该服务可用于为基于文本的地理位置搜索提供自动补全功能，方法是在用户输入内容时返回商家、地址和地图注点等地点。

地点自动补全（旧版）请求

地点自动补全（旧版）是 Places API 的一部分，与 Places API 共享 API 密钥和配额。

地点自动补全服务（旧版）可以根据完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Codes。这样，应用就可以在用户输入内容时发送查询，从而即时进行地点预测。

您必须正确设置 Plus Code 的格式。这意味着，您必须将加号进行网址转义，使其变为 %2B，并且必须将空格进行网址转义，使其变为 %20。

  • 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码。例如，网址转义全局代码 849VCWC8+R9 是 849VCWC8%2BR9。
  • 混合代码是至少包含 6 个字符的区域代码，具有明确的位置信息。例如，经过网址转义的复合代码 CWC8+R9 Mountain View, CA, USA 为 CWC8%2BR9%20Mountain%20View%20CA%20USA。

返回的预测结果旨在呈现给用户，以帮助他们选择所需的地点。如需详细了解返回的任何地点，您可以发送地点详情（旧版）请求。

地点自动补全（旧版）请求是以下形式的 HTTP 网址：

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

其中，output 可以是以下任一值：

  • json（推荐）表示以 JavaScript 对象表示法 (JSON) 格式输出
  • xml 表示以 XML 格式输出

必须提供某些参数才能发起“地点自动补全（旧版）”请求。 依照网址的标准，所有参数都使用“与”符号 (&) 分隔。下面列出了参数及其可能的值。

必需参数

  • 输入

    要搜索的文本字符串。地点自动补全服务将根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。

可选参数

  • 组件

    您希望将结果限制在其中的一组地点。 您可以使用组件按最多 5 个国家/地区进行过滤。 国家/地区必须以兼容 ISO 3166-1 Alpha-2 的双字符国家/地区代码形式传递。例如：components=country:fr 会将搜索结果限制为法国境内的地点。如果要指定多个国家/地区，则必须传递多个 country:XX 过滤条件，并使用竖线字符 | 作为分隔符。例如： components=country:us|country:pr|country:vi|country:gu|country:mp 会将搜索结果限制为美国及其未合并的自治领内的地点。

    注意：如果您使用国家/地区代码传递国家/地区时收到意外结果，请确认您使用的代码是否包含您要定位的国家/地区、附属地区以及特殊地理位置区域。如需了解代码相关信息，请参阅维基百科：ISO 3166 国家/地区代码列表或访问 ISO 在线浏览平台。

  • language

    返回结果所用的语言。

    • 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
    • 如果未提供 language，API 会尝试使用 Accept-Language 标头中指定的首选语言。
    • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为了实现这一目标，它会返回本地语言的街道地址，并在必要时根据首选语言将地址音译为用户可读的文字。所有其他地址均以首选语言返回。地址组成部分全部以同一种语言返回，该语言是从第一个组成部分中选择的。
    • 如果首选语言中没有相应名称，API 会使用最接近的匹配项。
    • 首选语言对 API 选择返回的结果集以及返回顺序有一定影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。例如，utca 和 tér 是匈牙利语中“街道”的同义词。

  • 地理位置

    要检索地点信息所围绕的点。必须指定为 latitude,longitude。指定位置时，还必须提供 radius 参数。如果未提供 radius，系统会忽略 location 参数。

    使用文本搜索 API 时，如果 `query` 包含明确的位置信息（例如“巴塞罗那的市场”），则可能会替换 `location` 参数。

  • locationbias

    通过指定半径加纬度/经度或表示矩形点的两个纬度/经度对，优先显示指定区域内的结果。如果未指定此参数，API 会默认使用 IP 地址偏差。

    • IP 偏差：指示 API 使用 IP 地址偏差。传递字符串 ipbias（此选项没有其他参数）。
    • 圆形：一个字符串，用于指定半径（以米为单位）以及纬度/经度（以十进制度为单位）。请使用以下格式：circle:radius@lat,lng。
    • 矩形：一个字符串，用于指定两个十进制度纬度/经度对，分别表示矩形的西南点和东北点。请使用以下格式：rectangle:south,west|north,east。请注意，东西值会封装到 -180 到 180 的范围内，南北值会限制到 -90 到 90 的范围内。

  • locationrestriction

    通过指定半径加纬度/经度或表示矩形点的两个纬度/经度对，将结果限制在指定区域内。

    • 圆形：一个字符串，用于指定半径（以米为单位）以及纬度/经度（以十进制度为单位）。请使用以下格式：circle:radius@lat,lng。
    • 矩形：一个字符串，用于指定两个十进制度纬度/经度对，分别表示矩形的西南点和东北点。请使用以下格式：rectangle:south,west|north,east。请注意，东西值会封装到 -180 到 180 的范围内，南北值会限制到 -90 到 90 的范围内。

  • offset

    服务用于匹配预测结果的输入字词中最后一个字符的位置。例如，如果输入为 Google，偏移量为 3，则该服务将匹配 Goo。由偏移量确定的字符串仅与输入字词中的第一个字词匹配。例如，如果输入字词为 Google abc，偏移量为 3，则服务将尝试与 Goo abc 进行匹配。如果未提供偏移量，服务将使用整个期限。偏移量通常应设置为文本光标的位置。

  • 源

    用于计算到目的地（以 distance_meters 形式返回）的直线距离的起点。如果省略此值，则不会返回直线距离。必须指定为 latitude,longitude。

  • 半径

    定义返回地点结果的距离范围（以米为单位）。您可以传递 location 和 radius 参数，使结果偏向指定圆形区域。这样做会指示地点服务优先显示该圆形区域内的结果；指定区域以外的结果可能仍会显示。

    系统会自动将半径限制为最大值，具体取决于搜索类型和其他参数。

    • 自动补全：50,000 米
    • 附近搜索：
      • 使用 keyword 或 name：50,000 米
      • 不含 keyword 或 name
        • 最高可达 50,000 米，根据区域密度动态调整，不受 rankby 参数的影响。
        • 使用 rankby=distance 时，系统不会接受半径参数，并会返回 INVALID_REQUEST。
    • 查询自动补全：50,000 米
    • 文本搜索：5 万米

  • 区域

    地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（代表“大不列颠及北爱尔兰联合王国”）。

  • sessiontoken

    一个随机字符串，用于标识自动填充会话以进行结算。

    会话在用户开始输入查询内容时开始，并在用户选择地点且系统执行“地点详情”调用时结束。在每个会话中，用户可以输入多项查询内容，并最终选择一个地点。会话中每个请求所用的 API 密钥必须属于同一 Google Cloud 控制台项目。会话结束后，令牌将失效；您的应用必须为每个会话生成一个新的令牌。如果您省略 sessiontoken 参数或重复使用会话令牌，系统会按未提供会话令牌的情况为会话计费（每个请求均单独结算）。

    我们建议您遵循以下准则：

    • 针对所有自动补全会话使用会话令牌。
    • 为每个会话生成一个新的令牌。建议使用版本 4 UUID。
    • 确保会话中用于所有“地点自动补全”请求和“地点详情”请求的 API 密钥属于同一 Cloud 控制台项目。
    • 请务必为每个新会话传递唯一的会话令牌。针对多个会话使用同一令牌会导致每个请求被单独计费。

  • strictbounds

    仅返回严格位于由 location 和 radius 界定的区域内的地点。这是一种限制，而不是偏差，这意味着即使结果与用户输入匹配，也不会返回该区域以外的结果。

  • 类型

    您可以通过传递 types 参数，将“地点自动补全”请求的结果限定为特定类型。此参数会指定某个类型或类型集合，如地点类型中所列。如果未指定任何内容，则返回所有类型。

    一个地点只能有一个主要类型，该类型必须是表 1 或表 2 中列出的类型。例如，提供餐饮服务的酒店可能仅返回 types=lodging，而不返回 types=restaurant。

    对于 types 参数的值，您可以指定以下任一值：

    • 最多可包含表 1 或表 2 中的五个值。对于多个值，请使用 |（竖线）分隔每个值。例如：

      types=book_store|cafe

    • 表 3 中的任意单个受支持的过滤条件。您不能混用类型集合。

    如果出现以下情况，请求会遭到拒绝，并显示 INVALID_REQUEST 错误：

    • 指定了超过五种类型。
    • 存在任何无法识别的类型。
    • 将表 1 或表 2 中的任意类型与表 3 中的任意过滤条件搭配使用。

地点自动补全（旧版）示例

请求查找加利福尼亚州旧金山中心区域内包含“Amoeba”字符串的商家：

网址

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

同一请求，但限制为仅返回旧金山阿什伯里街和海特街方圆 500 米内的结果：

网址

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

以下示例请求包含“Vict”的地址，并以法语显示结果：

网址

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

curl

curl -L -X GET '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

curl

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

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

地点自动补全（旧版）响应

地点自动补全（旧版）响应以请求的网址路径中 output 标志所指示的格式返回。以下结果表明了使用以下参数的查询可能会返回的结果：

网址

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

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>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

字段 必需 类型 说明
required Array<PlaceAutocompletePrediction>

包含预测数组。

如需了解详情，请参阅 PlaceAutocompletePrediction。

required PlacesAutocompleteStatus

包含请求的状态，可能还包含调试信息，以帮助您跟踪请求失败的原因。

如需了解详情，请参阅 PlacesAutocompleteStatus。

可选 字符串

当服务返回的状态代码不是 OK< 时，响应对象中可能包含额外的 error_message 字段。此字段包含有关给定状态代码背后原因的更详细信息。此字段并非始终会返回，并且其内容可能会发生变化。
可选 数组<string>

当服务返回有关请求规范的其他信息时，响应对象中可能会包含额外的 info_messages 字段。此字段仅针对成功请求返回。它可能并不总是返回，并且其内容可能会发生变化。

结果中特别值得关注的是 place_id 元素，该元素可用于通过单独的查询请求有关地点的更具体详情。请参阅地点详情（旧版）请求。

XML 响应由一个 <AutocompletionResponse> 元素组成，该元素包含两种类型的子元素：

  • 单个 <status> 元素包含有关请求的元数据。请参阅下文中的状态代码。
  • 零个或多个 <prediction> 元素，每个元素都包含单个地点的信息。如需了解这些结果，请参阅地点自动补全（旧版）结果。Places API 最多返回 5 个结果。

除非您的应用因某种原因需要 xml，否则我们建议您使用 json 作为首选输出标志。 处理 XML 树需要格外小心，以便您引用正确的节点和元素。如需有关处理 XML 的帮助，请参阅使用 XPath 处理 XML。

PlacesAutocompleteStatus

服务返回的状态代码。

  • OK：表示 API 请求成功。
  • ZERO_RESULTS 表示搜索成功，但未返回任何结果。如果搜索传递的边界位于偏远位置，则可能会发生这种情况。
  • INVALID_REQUEST 表示 API 请求格式有误，通常是因为缺少 input 参数。
  • OVER_QUERY_LIMIT 表示以下任一情况：
    • 您已超出 QPS 限额。
    • 您的账号尚未启用结算功能。
    • 超出了每月 200 美元的赠金或您设定的用量上限。
    • 提供的付款方式不再有效（例如，信用卡已过期）。
    如需详细了解如何解决此错误，请参阅地图常见问题解答。
  • REQUEST_DENIED 表示您的请求已遭拒，通常是因为：
    • 请求中缺少 API 密钥。
    • key 参数无效。
  • UNKNOWN_ERROR：表示出现未知错误。

当 Places 服务返回搜索结果（JSON 格式）时，会将这些结果放置在 predictions 数组中。即使服务未返回任何结果（例如，如果 location 是远程的），它仍会返回一个空的 predictions 数组。XML 响应包含零个或多个 <prediction> 元素。

PlaceAutocompletePrediction

字段 必需 类型 说明
required 字符串

包含返回结果的简单易懂的名称。对于 establishment 结果，这通常是商家名称。此内容应按原样读取。请勿以程序化方式解析设置了格式的地址。
required 数组<PlaceAutocompleteMatchedSubstring>

一个子字符串列表，用于描述输入字词在预测结果文本中的位置，以便在选择该字词时突出显示它。

如需了解详情，请参阅 PlaceAutocompleteMatchedSubstring。

required PlaceAutocompleteStructuredFormat

提供可在自动补全结果中显示的预格式化文本。此内容应按原样读取。请勿以程序化方式解析设置了格式的地址。

如需了解详情，请参阅 PlaceAutocompleteStructuredFormat。

required Array<PlaceAutocompleteTerm>

包含一个术语数组，用于标识返回的说明的每个部分（说明的每个部分通常以英文逗号结尾）。数组中的每个条目都有一个 value 字段（包含相应术语的文本）和一个 offset 字段（用于定义相应术语在说明中的起始位置，以 Unicode 字符衡量）。

如需了解详情，请参阅 PlaceAutocompleteTerm。

可选 整数

与原点的直线距离（以米为单位）。此字段仅针对使用 origin 发出的请求返回。

可选 字符串

唯一标识地点的文本标识符。如需检索地点的相关信息，请在 Places API 请求的 placeId 字段中传递此标识符。如需详细了解地点 ID，请参阅地点 ID 概览。

可选 字符串

请参阅 place_id。
可选 数组<string>

包含适用于相应地点的类型数组。例如： [ "political", "locality" ] 或 [ "establishment", "geocode", "beauty_salon" ]。该数组可以包含多个值。详细了解地点类型。

PlaceAutocompleteMatchedSubstring

字段 必需 类型 说明
required 数值

预测结果文本中匹配的子字符串的长度。
required 数值

预测结果文本中匹配的子字符串的起始位置。

PlaceAutocompleteStructuredFormat

字段 必需 类型 说明

main_text

required 字符串

包含预测的主要文本，通常是地名。

main_text_matched_substrings

required 数组<PlaceAutocompleteMatchedSubstring>

包含一个数组，其中包含 offset 值和 length。这些值描述了所输入字词在预测结果文本中的位置，以便在选择该字词时突出显示它。

如需了解详情，请参阅 PlaceAutocompleteMatchedSubstring。

secondary_text

可选 字符串

包含预测结果的辅助文本，通常是相应地点的地理位置。

secondary_text_matched_substrings

可选 数组<PlaceAutocompleteMatchedSubstring>

包含一个数组，其中包含 offset 值和 length。这些值描述了所输入字词在预测结果文本中的位置，以便在选择该字词时突出显示它。

如需了解详情，请参阅 PlaceAutocompleteMatchedSubstring。

PlaceAutocompleteTerm

字段 必需 类型 说明
required 数值

定义相应字词在描述中的起始位置（以 Unicode 字符为单位）

required 字符串

相应条款的文本。

地点自动补全（旧版）优化

本部分介绍了帮助您充分利用地点自动补全（旧版）服务的最佳实践。

下面列出了一些一般准则：

费用优化最佳实践

基本费用优化

为了优化地点自动补全（旧版）服务的使用费用，请在地点详情（旧版）和地点自动补全（旧版）微件中使用字段掩码，以便仅返回所需的地点自动补全（旧版）数据字段。

高级费用优化

请考虑通过程序化方式实现地点自动补全（旧版），以便采用 SKU：自动补全 - 按请求结算定价模式，并请求关于所选地点（而不是地点详情 [旧版]）的 Geocoding API 结果。如果同时满足以下两个条件，与采用“按会话”（基于会话）定价模式相比，将“按请求”定价模式与 Geocoding API 搭配使用的性价比更高：

  • 如果您只需要用户所选地点的纬度/经度或地址，那么采用 Geocoding API 提供此类信息所需的费用会低于调用地点详情（旧版）。
  • 如果用户平均在不超过四次地点自动补全（旧版）联想查询请求之内选择自动补全联想查询结果，那么“按请求”定价模式可能会比“按会话”定价模式的性价比更高。
如果在选择符合您需求的地点自动补全（旧版）实现方面需要帮助，请选择与以下问题的答案相对应的标签页。

除了所选预测结果的地址和纬度/经度外，您的应用是否需要任何其他信息？

是，需要更多详细信息

将基于会话的地点自动补全（旧版）与地点详情（旧版）搭配使用。
由于您的应用需要地点详情（旧版），例如地点名称、商家状态或营业时间，因此您在实现地点自动补全（旧版）时应使用会话令牌（以编程方式或内置于 JavaScript、Android 或 iOS widget 中），每个会话使用一个会话令牌，并根据您请求的地点数据字段，使用适用的地点数据 SKU。1

widget 实现
会话管理功能自动内置于 JavaScript、 Android 或 iOS widget 中。这包括针对所选预测结果的“地点自动补全（旧版）”请求和“地点详情（旧版）”请求。请务必指定 fields 参数，以确保您只请求所需的地点自动补全（旧版）数据字段。

程序化实现
在“地点自动补全”（旧版）请求中使用会话令牌。在请求关于所选预测结果的地点详情（旧版）时，添加以下参数：

  1. “地点自动补全（旧版）”响应中的地点 ID
  2. “地点自动补全（旧版）”请求中使用的会话令牌
  3. fields 参数，用于指定您所需的地点自动补全（旧版）数据字段

否，只需要地址和位置信息

对于您的应用，Geocoding API 可能比地点详情（旧版）性价比更高，具体取决于您使用地点自动补全（旧版）的性能。每个应用的地点自动补全（旧版）效率各有不同，具体取决于用户输入的内容、使用应用所在的位置，以及是否遵循了性能优化最佳实践。

为了回答以下问题，请分析用户在您的应用中选择地点自动补全（旧版）预测结果之前平均会输入多少个字符。

平均而言，用户是否能够在不超过四次请求之内选择地点自动补全（旧版）预测结果？

是

在不使用会话令牌的情况下以程序化方式实现地点自动补全（旧版），并针对所选的地点预测调用 Geocoding API。
Geocoding API 提供地址和纬度/经度坐标。 发出四次自动补全 - 按请求结算请求加上针对所选地点预测调用 Geocoding API 的费用低于按会话结算的地点自动补全（旧版）费用。1

您可以考虑采用性能最佳实践，帮助用户以更少的字符找到所需的预测结果。

否

将基于会话的地点自动补全（旧版）与地点详情（旧版）搭配使用。
由于在用户选择“地点自动补全（旧版）”预测结果之前，您预计发出的请求的平均数量超过了按会话结算的价格，因此您在实现“地点自动补全（旧版）”时，应为“地点自动补全（旧版）”请求和关联的“地点详情（旧版）”请求使用按会话结算的会话令牌。 1

widget 实现
会话管理功能自动内置于 JavaScript、 Android 或 iOS widget 中。这包括针对所选预测结果的“地点自动补全（旧版）”请求和“地点详情（旧版）”请求。请务必指定 fields 参数，以确保您只请求所需的字段。

程序化实现
在“地点自动补全”（旧版）请求中使用会话令牌。 在请求关于所选预测结果的地点详情（旧版）时，添加以下参数：

  1. “地点自动补全（旧版）”响应中的地点 ID
  2. “地点自动补全（旧版）”请求中使用的会话令牌
  3. fields 参数，用于指定地址和几何图形等基本数据字段

考虑延迟“地点自动补全（旧版）”请求
您可以采取一些策略，例如延迟“地点自动补全（旧版）”请求，直到用户输入前三个或四个字符，从而减少应用发出的请求数量。例如，在用户输入第三个字符后，针对每个字符发出地点自动补全（旧版）请求，这意味着如果用户输入七个字符，然后选择一个预测结果，而您针对该预测结果发出一个 Geocoding API 请求，则总费用将为 4 次地点自动补全（旧版）按请求结算的费用 + Geocoding 费用。1

如果延迟请求会导致平均程序化请求次数低于四次，您可以按照使用 Geocoding API 提高地点自动补全（旧版）性能的实现指南操作。请注意，如果用户希望每次输入新的字符后都能看到预测结果，可能会将延迟请求视为时间上的延迟。

您可以考虑采用性能最佳实践，帮助用户以较少的字符找到所需的预测结果。

  1. 如需了解费用，请参阅 Google Maps Platform 价格表。

性能最佳实践

下面的指南介绍了优化地点自动补全（旧版）性能的方式：

  • 向地点自动补全（旧版）实现添加国家/地区限制、位置自定义调整和语言偏好设置（适用于程序化实现）。您无需为 widget 进行语言偏好设置，因为它们会从用户的浏览器或移动设备中选择语言偏好设置。
  • 如果地点自动补全（旧版）附有地图，您可以根据地图视口来设置位置偏向。
  • 如果用户未选择任一地点自动补全（旧版）预测结果，通常是因为这些预测结果都不是所需的结果地址，您可以重复使用原始用户输入来尝试获取更相关的结果：
    • 如果您希望用户仅输入地址信息，请在调用 Geocoding API 时重复使用原始用户输入。
    • 如果您希望用户按名称或地址查询某个地点，请使用“地点详情（旧版）”请求。如果希望仅显示特定区域内的结果，请使用位置自定义调整。
    适合回退到 Geocoding API 的其他场景包括：
    • 输入子地址的用户，例如建筑物内特定单元或公寓的地址。例如，捷克地址“Stroupežnického 3191/17, Praha”会在地点自动补全（旧版）中生成部分预测结果。
    • 用户在输入地址时，需要输入路段前缀，例如纽约的“23-30 29th St, Queens”或夏威夷考爱岛“47-380 Kamehameha Hwy, Kaneohe”。

位置信息偏差

通过传递 location 参数和 radius 参数，使结果偏向指定区域。这会指示地点自动补全（旧版）优先显示定义区域内的结果。指定区域以外的结果可能仍会显示。您可以使用 includedRegionCodes 参数过滤结果，以仅显示指定国家/地区内的地点。

限制位置

通过传递 locationRestriction 参数，将结果限制在指定区域内。

您还可以添加 strictbounds 参数，将结果限制为由 location 和 radius 参数定义的区域。这会指示地点自动补全（旧版）仅返回该区域内的结果。