此产品或功能处于旧版状态。如需详细了解“旧版”状态，请参阅旧版产品和功能。如需迁移到 Places API（新版），请参阅迁移指南。

查询自动补全（旧版）

欧洲经济区 (EEA) 开发者

注意：服务器端和客户端库

Places API 也适用于适用于 Google 地图服务的 Java 客户端、 Python 客户端、Go 客户端和 Node.js 客户端。 Places API 和客户端库适用于服务器应用。

如果您要构建客户端应用，请参阅 Places SDK for Android（新版）、Places SDK for iOS（新版）和 Maps JavaScript API 地点库。

查询自动补全（旧版）可用于为基于文本的地理搜索提供查询预测，方法是在您输入时返回建议的查询。

查询自动补全（旧版）请求

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

借助查询自动补全（旧版），您可以向应用添加即时地理查询预测。用户无需搜索特定地点，只需输入类别搜索（例如“纽约附近的披萨店”），服务就会返回与该字符串匹配的建议查询列表。由于查询自动补全（旧版）可以匹配完整字词和子字符串，因此应用可以在用户输入时发送查询，从而提供即时预测。

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

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

其中 output 可以是 json 或 xml。

启动查询自动补全（旧版）请求需要某些参数。依照网址的标准，所有参数都使用“与”符号 (&) 分隔。下面列出了参数及其可能的值。

必需参数

输入

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

可选参数

language

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

将一个点定义为 latitude,longitude 坐标，围绕该点进行搜索。地点服务使用地理位置来偏向搜索，优先显示由 location 和 radius 定义的区域内的结果；指定区域以外的结果可能仍会显示。

如果 query 包含显式地理位置（例如 Market in Barcelona），则 location 参数可能会被替换。在查询周围使用引号也可能会影响赋予 location 和 radius 的权重。
offset

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

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

半径将根据搜索类型和其他参数自动限制为最大值。
- 自动补全：50,000 米
- 附近搜索：
  - 使用 keyword 或 name：50,000 米
  - 不使用 keyword 或 name
    - 最多 50,000 米，根据区域密度动态调整，与 rankby 参数无关。
    - 使用 rankby=distance 时，系统将不接受半径参数，并返回 INVALID_REQUEST。
- 查询自动补全：50,000 米
- 文本搜索：50,000 米

查询自动补全（旧版）示例

网址

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

请求“Pizza near Par”，结果为法语：

网址

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &language=fr
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&language=fr&key=YOUR_API_KEY'

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

查询自动补全（旧版）响应

查询自动补全（旧版）响应以网址请求路径中的 output 标志指示的格式返回。以下结果是针对具有以下参数的查询返回的：

网址

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "pizza near Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris" },
            { "offset": 18, "value": "France" },
          ],
      },
      {
        "description": "pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Pari Chowk" },
            { "offset": 23, "value": "NRI City" },
            { "offset": 33, "value": "Omega II" },
            { "offset": 43, "value": "Noida" },
            { "offset": 50, "value": "Uttar Pradesh" },
            { "offset": 65, "value": "India" },
          ],
      },
      {
        "description": "pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 22 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 16 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Disneyland Park" },
            { "offset": 28, "value": "Disneyland Drive" },
            { "offset": 46, "value": "Anaheim" },
            { "offset": 55, "value": "CA" },
            { "offset": 59, "value": "USA" },
          ],
      },
      {
        "description": "pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 36 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 30 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Cathédrale Notre-Dame de Paris" },
            { "offset": 43, "value": "Parvis Notre-Dame - place Jean-Paul-II" },
            { "offset": 83, "value": "Paris" },
            { "offset": 90, "value": "France" },
          ],
      },
      {
        "description": "pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris Beauvais Airport" },
            { "offset": 35, "value": "Route de l'Aéroport" },
            { "offset": 56, "value": "Tillé" },
            { "offset": 63, "value": "France" },
          ],
      },
    ],
  "status": "OK",
}

XML

      
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>France</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Pari Chowk</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NRI City</value>
   <offset>23</offset>
  </term>
  <term>
   <value>Omega II</value>
   <offset>33</offset>
  </term>
  <term>
   <value>Noida</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Uttar Pradesh</value>
   <offset>50</offset>
  </term>
  <term>
   <value>India</value>
   <offset>65</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Disneyland Park</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Disneyland Drive</value>
   <offset>28</offset>
  </term>
  <term>
   <value>Anaheim</value>
   <offset>46</offset>
  </term>
  <term>
   <value>CA</value>
   <offset>55</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>59</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>22</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>16</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Cathédrale Notre-Dame de Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Parvis Notre-Dame - place Jean-Paul-II</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>83</offset>
  </term>
  <term>
   <value>France</value>
   <offset>90</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>36</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>30</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris Beauvais Airport</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Route de l'Aéroport</value>
   <offset>35</offset>
  </term>
  <term>
   <value>Tillé</value>
   <offset>56</offset>
  </term>
  <term>
   <value>France</value>
   <offset>63</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

当地点服务从搜索中返回 JSON 结果时，会将它们放在 predictions 数组中。即使服务未返回任何结果（例如，如果 location 是远程的），它仍然会返回一个空的 predictions 数组。XML 响应由零个或多个 <prediction> 元素组成。

PlacesQueryAutocompleteResponse

字段	必需	类型	说明
`predictions`	必需	数组<PlaceAutocompletePrediction>	包含预测结果数组。如需了解详情，请参阅 PlaceAutocompletePrediction 。
`status`	必需	PlacesAutocompleteStatus	包含请求的状态，可能还包含调试信息，以帮助您跟踪请求失败的原因。如需了解详情，请参阅 PlacesAutocompleteStatus。
`error_message`	可选	字符串	当服务返回除 `OK`以外的状态代码时，响应对象中可能会有一个额外的 `error_message` 字段。此字段包含有关给定状态代码背后原因的更详细信息。此字段并非总是返回，其内容可能会发生变化。
`info_messages`	可选	数组<string>	当服务返回有关请求规范的额外信息时，响应对象中可能会有一个额外的 `info_messages`字段。此字段仅针对成功的请求返回。它并非总是返回，其内容可能会发生变化。

PlacesAutocompleteStatus

服务返回的状态代码。

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

PlaceAutocompletePrediction

字段	必需	类型	说明
`description`	必需	字符串	包含返回结果的简单易懂的名称。对于 `establishment` 结果，这通常是商家名称。此内容应按原样读取。请勿以程序化方式解析设置了格式的地址。
`matched_substrings`	必需	数组<PlaceAutocompleteMatchedSubstring>	一个子字符串列表，用于描述输入字词在预测结果文本中的位置，以便在需要时突出显示该字词。如需了解详情，请参阅 PlaceAutocompleteMatchedSubstring 。
`structured_formatting`	必需	PlaceAutocompleteStructuredFormat	提供可在自动补全结果中显示的预先设置格式的文本。此内容应按原样读取。请勿以程序化方式解析设置了格式的地址。如需了解详情，请参阅 PlaceAutocompleteStructuredFormat 。
`terms`	必需	数组<PlaceAutocompleteTerm>	包含一个术语数组，用于标识返回的描述的每个部分（描述的某个部分通常以英文逗号结尾）。数组中的每个条目都有一个 `value` 字段（包含术语的文本）和一个 `offset` 字段（用于定义此术语在描述中的起始位置，以 Unicode 字符为单位）。如需了解详情，请参阅 PlaceAutocompleteTerm。
`distance_meters`	可选	整数	与原点的直线距离（以米为单位）。此字段仅针对使用 `origin` 发出的请求返回。
`place_id`	可选	字符串	用于唯一标识地点的文本标识符。如需检索地点的相关信息，请在 Places API 请求的 placeId 字段中传递此标识符。如需详细了解地点 ID，请参阅地点 ID 概览。
`reference`	可选	字符串	`reference` 已弃用。请参阅 place_id。
`types`	可选	数组<string>	包含适用于此地点的类型数组。例如： `[ "political", "locality" ]` 或 `[ "establishment", "geocode", "beauty_salon" ]`。该数组可以包含多个值。详细了解地点类型。

PlaceAutocompleteMatchedSubstring

字段	必需	类型	说明
`length`	必需	数值	预测结果文本中匹配的子字符串的长度。
`offset`	必需	数值	预测结果文本中匹配的子字符串的起始位置。

PlaceAutocompleteStructuredFormat

字段	必需	类型	说明
`main_text`	必需	字符串	包含预测结果的主要文本，通常是地点的名称。
`main_text_matched_substrings`	必需	数组<PlaceAutocompleteMatchedSubstring>	包含一个数组，其中包含 `offset` 值和 `length`。这些描述了输入字词在预测结果文本中的位置，以便在需要时突出显示该字词。如需了解详情，请参阅 PlaceAutocompleteMatchedSubstring 。
`secondary_text`	可选	字符串	包含预测结果的辅助文本，通常是地点的地理位置。
`secondary_text_matched_substrings`	可选	数组<PlaceAutocompleteMatchedSubstring>	包含一个数组，其中包含 `offset` 值和 `length`。这些描述了输入字词在预测结果文本中的位置，以便在需要时突出显示该字词。如需了解详情，请参阅 PlaceAutocompleteMatchedSubstring 。

PlaceAutocompleteTerm

字段	必需	类型	说明
`offset`	必需	数值	定义此术语在描述中的起始位置，以 Unicode 字符为单位
`value`	必需	字符串	术语的文本。

查询自动补全（旧版） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

查询自动补全（旧版）请求

必需参数

输入

可选参数

language

地理位置

offset

半径

查询自动补全（旧版）示例

网址

curl

网址

curl

查询自动补全（旧版）响应

网址

curl

JSON

XML

PlacesQueryAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

查询自动补全（旧版）

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`