Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

查询自动补全（旧版）

欧洲经济区 (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 密钥和配额。

借助 Query Autocomplete（旧版），您可以向应用添加即时地理查询联想功能。用户可以输入类别搜索（例如“纽约附近的披萨店”），而不是搜索特定位置，该服务会返回与该字符串匹配的建议查询列表。由于 Query Autocomplete（旧版）可以匹配完整字词和子字符串，因此应用可以在用户输入内容时发送查询，从而即时进行预测。

Query Autocomplete（旧版）请求是采用以下形式的 HTTP 网址：

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

其中 output 可以是 json 或 xml。

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

必需参数

输入

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

可选参数

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 时，系统不接受 radius 参数，并会返回 INVALID_REQUEST。
- 查询自动补全：50,000 米
- 文本搜索：50,000 米

Query Autocomplete（旧版）示例

网址

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 密钥替换为您自己的密钥。

Query Autocomplete（旧版）响应

查询自动补全（旧版）响应会以网址请求路径中的 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`	required	Array<PlaceAutocompletePrediction>	包含一个由联想查询组成的数组。如需了解详情，请参阅 PlaceAutocompletePrediction。
`status`	required	PlacesAutocompleteStatus	包含请求的状态，可能还包含调试信息，以帮助您跟踪请求失败的原因。如需了解详情，请参阅 PlacesAutocompleteStatus。
`error_message`	可选	字符串	当服务返回 `OK` 以外的状态代码时，响应对象中可能会有一个额外的 `error_message` 字段。此字段包含有关给定状态代码背后原因的更详细信息。此字段不一定会返回，其内容可能会发生变化。
`info_messages`	可选	Array<string>	当服务返回有关请求规范的其他信息时，响应对象中可能会有一个额外的 `info_messages` 字段。只有成功的请求才会返回此字段。它可能并不总是返回，其内容可能会发生变化。

PlacesAutocompleteStatus

服务返回的状态代码。

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

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

PlaceAutocompletePrediction

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

PlaceAutocompleteMatchedSubstring

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

PlaceAutocompleteStructuredFormat

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

PlaceAutocompleteTerm

字段	必填	类型	说明
`offset`	required	数值	定义此字词在说明中的起始位置（以 Unicode 字符为单位）
`value`	required	字符串	条款的文本。

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

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

必需参数

输入

可选参数

language

地理位置

offset

半径

Query Autocomplete（旧版）示例

网址

curl

网址

curl

Query Autocomplete（旧版）响应

网址

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`