此页面由 Cloud Translation API 翻译。

自动补全（新）

请选择平台： Android iOS JavaScript 网络服务

自动补全（新）服务是一项网络服务，可返回地点预测和查询预测结果以响应 HTTP 请求。在请求中，指定控制搜索区域的文本搜索字符串和地理边界。

自动补全（新）服务可以匹配输入内容的完整字词和子字符串，从而解析地点名称、地址和 Plus Codes。因此，应用可以在用户输入内容时发送查询，从而即时提供地点和查询预测。

Autocomplete（新）API 的响应可以包含两种类型的预测：

地点预测：根据指定的输入文本字符串和搜索区域显示地点，如商家、地址和地图注点。默认情况下会返回地点预测。
查询预测：与输入文本字符串和搜索区域匹配的查询字符串。默认情况下，查询预测不会返回。使用 includeQueryPredictions 请求参数将查询预测添加到响应中。

例如，您可以使用包含部分用户输入的字符串“Sicilian piz”作为输入来调用 API，其中搜索区域仅限于加利福尼亚州旧金山。然后，响应中包含与搜索字符串和搜索区域匹配的地点预测列表（例如名为“Sicilian Pizza Kitchen”的餐厅），以及该地点的详细信息。

系统会向用户显示返回的“地点预测”，以帮助他们选择所需的地点。您可以发出地点详情（新）请求，以获取有关返回的任何地点预测结果的更多信息。

响应还可以包含与搜索字符串和搜索区域匹配的查询预测列表，例如“西西里披萨和意大利面”。响应中的每个查询预测都包含 text 字段，该字段包含建议的文本搜索字符串。使用该字符串作为文本搜索（新）的输入，以执行更详细的搜索。

在 API Explorer 中，您可以发出实时请求，以便您熟悉 API 和 API 选项：

试试看！

“自动补全（新）”请求

“自动补全（新）”请求是对网址采用的 HTTP POST 请求，格式如下：

https://places.googleapis.com/v1/places:autocomplete

将 JSON 请求正文或标头中的所有参数作为 POST 请求的一部分传递。例如：

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

关于响应

Autocomplete（新）会返回一个 JSON 对象作为响应。在响应中：

suggestions 数组包含所有预测的地点和查询（根据其感知的相关程度排序）。每个地点由 placePrediction 字段表示，每个查询由 queryPrediction 字段表示。
placePrediction 字段包含有关单个地点预测的详细信息，包括地点 ID 和文本说明。
queryPrediction 字段包含有关单个查询预测的详细信息。

注意：自动补全（新）总共会返回 5 个预测结果：placePredictions、queryPredictions 或两者的组合，具体取决于请求。例如，如果请求未设置 includeQueryPredictions，则响应正文最多包含五个 placePredictions。如果请求设置 includeQueryPredictions，则响应正文最多包含五个预测结果（placePredictions 和 queryPredictions 的组合）。

完整的 JSON 对象格式如下：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

必需参数

输入

要搜索的文本字符串。指定完整字词和子字符串、地点名称、地址和 Plus Codes。自动补全（新）服务会根据此字符串返回候选匹配项，并按照其判断的相关性对结果进行排序。

可选参数

includedPrimaryTypes

从表 A 或表 B 中列出的类型中，一个地点只能有一个主要类型。例如，主要类型可能是 "mexican_restaurant" 或 "steak_house"。

默认情况下，无论地点所关联的主要类型值如何，API 都会根据 input 参数返回所有地点。通过传递 includedPrimaryTypes 参数，将结果限制为特定主要类型或主要类型。

使用此参数，最多可指定表 A 或表 B 中的五个类型值。地点必须与某个指定的主要类型值匹配，才能包含在响应中。

不过，此参数还可能包含 (regions) 或 (cities) 中的一个。(regions) 类型的集合过滤器适用于区域或分区，例如社区和邮政编码。(cities) 类型集合用于过滤 Google 已识别为城市的地点。

如果出现以下情况，则请求将被拒绝并出现 INVALID_REQUEST 错误：
- 指定了超过五种类型。
- 除 (cities) 或 (regions) 之外，还可以指定任何类型。
- 指定了所有无法识别的类型。
注意：includedPrimaryTypes 参数仅适用于地点的主要类型，不适用于与地点关联的所有类型。虽然每个地点都有主要类型，但 Places API（新）并非支持所有主要类型。支持的类型包括表 A 或表 B 中列出的类型。
includeQueryPredictions

如果为 true，则响应同时包含地点和查询预测。默认值为 false，表示响应仅包含地点预测。
includedRegionCodes

仅包含来自指定区域列表的结果，该列表指定为最多包含 15 个 ccTLD（“顶级域名”）双字符值的数组。如果省略，则不会对响应应用任何限制。例如，要将区域限制为德国和法国：
```
    "includedRegionCodes": ["de", "fr"]
```
如果您同时指定 locationRestriction 和 includedRegionCodes，结果将位于这两项设置的交集区域中。
inputOffset

从零开始的 Unicode 字符偏移量，表示 input 中的光标位置。光标位置会影响返回的预测结果。如果为空，则默认长度为 input。

注意：在初始非公开预览版中，此属性称为 predictionTermOffset。
languageCode

返回结果时使用的首选语言。如果 input 中使用的语言与 languageCode 指定的值不同，或者返回的地点没有从当地语言到 languageCode 的翻译，结果可能会采用混合语言。
- 您必须使用 IETF BCP-47 语言代码指定首选语言。
- 如果未提供 languageCode，则 API 会使用 Accept-Language 标头中指定的值。如果二者都未指定，则默认值为 en。如果您指定的语言代码无效，API 会返回 INVALID_ARGUMENT 错误。
- 首选语言对 API 选择返回的结果集以及结果的返回顺序有较小的影响。这也会影响 API 纠正拼写错误的能力。
- 该 API 会尝试提供用户和当地居民都能看懂的街道地址，同时反映用户输入。地点预测的格式因每个请求中的用户输入而异。
  - 首先选择 input 参数中匹配的字词，使用与 languageCode 参数（如果可用）所指示的语言偏好设置一致的名称，否则使用最符合用户输入的名称。
  - 只有在选择匹配字词与 input 参数中的字词匹配后，街道地址才会采用用户可阅读的脚本中的当地语言格式（如有可能）。
  - 选择匹配字词以匹配 input 参数中的字词后，系统会以首选语言返回所有其他地址。如果某个名称没有以首选语言提供，API 会使用最接近的匹配项。
locationBias 或 locationRestriction

您可以指定 locationBias 或 locationRestriction 来定义搜索区域，但不能同时指定这两者。您可将 locationRestriction 视为指定结果必须位于哪个区域，将 locationBias 视为指定结果必须靠近但可位于该区域之外的区域。

注意：如果您同时省略 locationBias 和 locationRestriction，则该 API 默认使用 IP 自定义调整。借助 IP 自定义调整，该 API 使用设备的 IP 地址来调整结果。
- locationBias
  
  指定要搜索的区域。此位置可充当偏差，这意味着可返回指定位置周围的结果，包括指定区域以外的结果。
- locationRestriction
  
  指定要搜索的区域。指定区域以外的结果不会返回。
将 locationBias 或 locationRestriction 区域指定为矩形视口或圆形。
- 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含 0.0 和 50000.0）。默认值为 0.0。对于 locationRestriction，您必须将半径设置为大于 0.0 的值。否则，请求不会返回任何结果。
  
  例如：
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- 矩形是一种纬度-经度视口，表示为两个呈对角线相反的 low 和高点。视口被视为封闭区域，也就是说，视口包含其边界。纬度边界必须介于 -90 度和 90 度（含）之间，经度边界必须介于 -180 度和 180 度（含）之间：
  - 如果 low = high，视口由该单点组成。
  - 如果 low.longitude > high.longitude，则反转经度范围（视口与 180 度经度线相交）。
  - 如果 low.longitude = -180 度且 high.longitude = 180 度，视口将包含所有经度。
  - 如果 low.longitude = 180 度且 high.longitude = -180 度，则经度范围为空。
  low 和 high 都必须填充，并且表示的框不能为空。视口为空会导致错误。
  
  例如，以下视口将纽约市完全包围：
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
发迹地

用于计算距目的地直线距离的起点（返回为 distanceMeters）。如果省略此值，将不会返回直线距离。必须指定为纬度和经度坐标：
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

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

如果您指定的地区代码无效，则 API 会返回 INVALID_ARGUMENT 错误。根据适用法律，该参数可能会影响结果。
sessionToken

会话令牌是用户生成的字符串，用于将“自动补全（新）”调用作为“会话”进行跟踪。自动补全（新）使用会话令牌将用户自动补全搜索的查询和选择阶段分组为一个单独的会话，以便进行结算。如需了解详情，请参阅会话令牌。

自动补全（新）示例

使用 locationRestriction 和 locationBias

默认情况下，该 API 使用 IP 自定义调整来控制搜索区域。通过 IP 自定义调整，该 API 使用设备的 IP 地址来调整结果。您可以视需要使用 locationRestriction 或 locationBias（但不能同时使用这两者）来指定要搜索的区域。

locationRestriction 用于指定要搜索的区域。指定区域以外的结果不会返回。在以下示例中，您使用 locationRestriction 将请求限制为以旧金山为中心、半径为 5000 米的圆形区域：

curl -X POST -d '{
  "input": "Amoeba",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

指定区域内的所有结果都包含在 suggestions 数组中：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

如果使用 locationBias，位置会充当偏差，这意味着系统会返回指定位置周围的结果，包括指定区域以外的结果。在下一个示例中，您将请求更改为使用 locationBias：

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

结果现在包含更多项，包括半径 5000 米以外的结果：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

使用 includePrimaryType

使用 includedPrimaryTypes 参数最多可以指定表 A、表 B 中的五个类型值，也可以仅指定 (regions) 或仅 (cities)。地点必须与某个指定的主要类型值匹配，才能包含在响应中。

在以下示例中，您指定了“Soccer”的 input 字符串，并使用 includedPrimaryTypes 参数将结果限制为 "sporting_goods_store" 类型的建筑物：

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

如果您省略 includedPrimaryTypes 参数，则结果可能会包含您不想要类型的建筑物，例如 "athletic_field"。

请求预测查询

默认情况下，查询预测不会返回。使用 includeQueryPredictions 请求参数将查询预测添加到响应中。例如：

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

suggestions 数组现在同时包含地点预测和查询预测，如上文关于响应部分所示。每个查询预测都包含 text 字段，该字段包含建议的文本搜索字符串。您可以发出文本搜索（新）请求，以获取有关任何返回的联想查询的更多信息。

注意：设置 includedRegionCodes 参数后，系统不会返回查询预测。

使用源

在此示例中，在请求中包含 origin 作为纬度和经度坐标。如果您添加了 origin，则 API 会在响应中包含 distanceMeters 字段，该字段包含从 origin 到目的地的直线距离。以下示例将原点设置为旧金山的中心：

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

响应现在包含 distanceMeters：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

试试看！

在 API Explorer 中，您可以发出示例请求，以便您熟悉 API 和 API 选项。

选择页面右侧的 API 图标。
（可选）展开显示标准参数 (Show standard parameters)，并将 fields 参数设置为字段掩码。
（可选）修改请求正文。
选择执行按钮。在弹出式窗口中，选择您要用于发出请求的账号。
在 API Explorer 面板中，选择展开图标以展开 API Explorer 窗口。

自动补全（新）

“自动补全（新）”请求

关于响应

必需参数

输入

可选参数

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

发迹地

regionCode

sessionToken

自动补全（新）示例

使用 locationRestriction 和 locationBias

使用 includePrimaryType

请求预测查询

使用源

试试看！