简介
Autocomplete（新版）是一项网络服务，可针对 HTTP 请求返回地点联想查询和查询联想。在请求中，指定文本搜索字符串和控制搜索区域的地理边界。
自动补全（新版）可以根据输入的完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Code。这样，应用就可以在用户输入内容时发送查询，从而即时进行地点和查询预测。
自动补全（新版）的响应可以包含两种类型的预测结果：
- 地点联想查询：根据指定的输入文本字符串和搜索区域，提供地点（例如商家、地址和地图注点）。默认情况下，系统会返回地点预测结果。
- 联想查询：与输入文本字符串和搜索区域匹配的查询字符串。默认情况下，系统不会返回联想查询。使用
includeQueryPredictions请求参数向响应添加查询联想。
例如，您调用 Autocomplete（新版），并使用包含部分用户输入“Sicilian piz”的字符串作为输入，同时将搜索区域限制为加利福尼亚州旧金山。然后，响应会包含与搜索字符串和搜索区域匹配的地点预测结果列表，例如名为“Sicilian Pizza Kitchen”的餐厅，以及有关该地点的详细信息。
返回的地点联想查询旨在呈现给用户，以帮助他们选择所需地点。您可以发出地点详情（新版）请求，以详细了解返回的任何地点预测。
响应还可能包含与搜索字符串和搜索区域匹配的联想查询列表，例如“Sicilian Pizza & Pasta”。响应中的每个联想查询都包含 text 字段，其中包含推荐的文本搜索字符串。将该字符串用作文本搜索（新版）的输入，以执行更详细的搜索。
借助 APIs 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
支持的参数
参数 |
说明 |
|---|---|
要搜索的文本字符串（完整字词、子字符串、地点名称、地址、Plus Code）。 |
|
|
逗号分隔列表，用于指定要在响应中返回哪些字段。 |
将结果限制为与最多五个指定主要类型之一匹配的地点。 |
|
如果为 true，则包含没有实际营业地点的商家（上门服务商家）。默认值为 false。 |
|
如果为 true，则在响应中同时包含地点和查询联想结果。默认值为 false。 |
|
最多包含 15 个双字符国家/地区代码的数组，用于将结果限制在这些国家/地区。 |
|
输入字符串中光标位置的 Unicode 字符偏移量（从零开始），会影响联想查询。默认值为输入长度。 |
|
结果的首选语言（IETF BCP-47 代码）。 默认为 Accept-Language 标头或“en”。 |
|
指定一个区域（圆形或矩形），使搜索结果偏向于该区域，但允许显示该区域以外的结果。不能与 locationRestriction 一起使用。 |
|
指定一个区域（圆形或矩形），以将搜索结果限制在该区域内。此区域以外的结果会被排除。 不能与 locationBias 一起使用。 |
|
用于计算到预测目的地的直线距离 (distanceMeters) 的起点（纬度、经度）。 |
|
用于设置回答格式和偏向建议的地区代码（例如“uk”“fr”）。 |
|
用户生成的字符串，用于将自动补全调用归入一个会话，以便进行结算。 |
关于响应
Autocomplete（新版）会返回一个 JSON 对象作为响应。 在响应结果中：
suggestions数组包含所有预测的地点和查询，并根据其感知相关性进行排序。每个地点都由一个placePrediction字段表示，每个查询都由一个queryPrediction字段表示。placePrediction字段包含有关单个地点联想查询的详细信息，包括地点 ID 和文本说明。- 为了更贴近
input参数中提供的用户输入，地点预测结果的文本说明可能包含地点、街道和其他地址组成部分的备用名称。这些备用名称可能与同一地点 ID 的地点详情结果中的displayName和地址字段中返回的名称不同。 - 在这种情况下，某些地点的备用名称可能与根据
languageCode参数预期的语言不同，具体取决于哪些名称与用户输入更匹配。
- 为了更贴近
queryPrediction字段包含有关单个联想查询的详细信息。
完整的 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 Code。 自动补全（新版）服务会根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。
可选参数
-
FieldMask
通过创建响应字段掩码，指定要在响应中返回的字段列表。 使用 HTTP 标头
X-Goog-FieldMask将响应字段掩码传递给方法。指定要返回的建议字段的逗号分隔列表。例如，检索建议的
suggestions.placePrediction.text.text和suggestions.queryPrediction.text.text。X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
使用
*可以检索所有字段。X-Goog-FieldMask: *
-
includeFutureOpeningBusinesses
如果值为
true，则返回预计在未来开业的商家。默认设置为false。 -
includedPrimaryTypes
一个地点只能有一个主要类型，该类型必须来自表 A 或表 B 中列出的类型。例如，主要类型可能是
"mexican_restaurant"或"steak_house"。默认情况下，无论与地点关联的主要类型值是什么，API 都会根据
input参数返回所有地点。通过传递includedPrimaryTypes参数，将结果限制为特定主要类型。使用此参数可指定表 A 或表 B 中的最多五个类型值。地点必须与指定的主要类型值之一匹配，才能包含在响应中。
此参数也可以改为包含
(regions)或(cities)之一。(regions)类型集合会过滤区域或分区，例如社区和邮政编码。(cities)类型集合会过滤出 Google 标识为城市的地点。如果出现以下情况，请求会被拒绝并显示
INVALID_REQUEST错误：- 指定了超过五种类型。
- 除了
(cities)或(regions)之外，还指定了任何类型。 - 指定了任何无法识别的类型。
-
includePureServiceAreaBusinesses
如果设置为
true，则响应中会包含为客户提供上门服务或送货上门，但没有实体营业地点的商家。如果设置为false，则 API 仅返回具有实体营业地点的商家。 -
includeQueryPredictions
如果为
true，则响应中会同时包含地点和查询联想结果。默认值为false，表示响应仅包含地点联想查询。 -
includedRegionCodes
仅包含指定地区列表中的结果，该列表指定为最多包含 15 个 ccTLD（“顶级域名”）双字符值的数组。如果省略，则不会对回答应用任何限制。例如，如需将区域限制为德国和法国，请运行以下命令：
"includedRegionCodes": ["de", "fr"]
如果您同时指定了
locationRestriction和includedRegionCodes，则结果位于这两项设置的交集区域。 -
inputOffset
从零开始的 Unicode 字符偏移量，表示
input中的光标位置。 光标位置可能会影响返回的联想查询。如果为空，则默认为input的长度。 -
languageCode
返回结果的首选语言。如果
input中使用的语言与languageCode指定的值不同，或者返回的地点没有从本地语言到languageCode的翻译，则结果可能会采用混合语言。- 您必须使用 IETF BCP-47 语言代码来指定首选语言。
-
如果未提供
languageCode，则 API 会使用Accept-Language标头中指定的值。如果两者均未指定，则默认值为en。如果您指定了无效的语言代码，此 API 会返回INVALID_ARGUMENT错误。 - 首选语言对 API 选择返回的结果集以及返回顺序有轻微影响。 这也会影响 API 纠正拼写错误的能力。
-
地点联想查询的格式因每个请求中的用户输入而异。
-
系统会优先选择
input参数中的匹配字词，并尽可能使用与languageCode参数指示的语言偏好一致的名称；否则，系统会使用与用户输入最匹配的名称。 -
地点名称可能会使用备用名称进行格式设置，以匹配
input参数中的字词，包括languageCode参数指示的语言以外的其他语言的名称。 -
街道地址采用本地语言格式，并尽可能采用用户可读的文字，但前提是已选择与
input参数中的字词匹配的字词。 -
在选择匹配字词以匹配
input参数中的字词后，所有其他地址都会以首选语言返回。如果首选语言中没有名称，API 会使用最接近的匹配项。
-
系统会优先选择
locationBias 或 locationRestriction
您可以指定
locationBias或locationRestriction（但不能同时指定这两者）来定义搜索区域。您可以将locationRestriction视为指定结果必须位于的区域，将locationBias视为指定结果必须靠近但可以位于该区域之外的区域。locationBias
指定要搜索的区域。此位置用作偏向，这意味着系统可能会返回指定位置周围的结果，包括指定区域之外的结果。
locationRestriction
指定要搜索的区域。系统不会返回指定区域以外的结果。
将
locationBias或locationRestriction区域指定为矩形视口或圆形。圆形由中心点和半径（以米为单位）定义。半径必须介于 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”（代表“大不列颠及北爱尔兰联合王国”）。
建议还会根据地区代码进行偏向。Google 建议根据用户的地区偏好设置来设置
regionCode。如果您指定了无效的地区代码，API 会返回
INVALID_ARGUMENT错误。该参数可能会根据适用法律影响结果。 -
sessionToken
会话令牌是用户生成的字符串，用于将 Autocomplete (New) 调用作为“会话”进行跟踪。自动补全（新版）使用会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。如需了解详情，请参阅会话令牌。
选择参数以使结果产生偏差
自动补全（新版）参数对搜索结果的影响各不相同。 下表根据预期结果提供了参数使用建议。| 参数 | 使用建议 |
|---|---|
regionCode |
根据用户的地区偏好设置进行设置。 |
includedRegionCodes |
设置此参数可将结果限制在指定区域列表中。 |
locationBias |
当您希望优先显示某个区域内或其周围的结果时，请使用此功能。如果适用，请将区域定义为用户正在查看的地图的视口。 |
locationRestriction |
仅在不应返回区域以外的结果时使用。 |
origin |
当需要到每个预测位置的直线距离时使用。 |
自动补全（新版）示例
使用 locationRestriction 将搜索范围限制在某个区域
locationRestriction 用于指定搜索区域。系统不会返回指定区域以外的结果。在以下示例中，您可以使用 locationRestriction 将请求限制在以旧金山为中心、半径为 5000 米的圆形区域内：
curl -X POST -d '{
"input": "Art museum",
"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/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
您还可以使用 locationRestriction 将搜索范围限制在矩形视口内。以下示例将请求限制为旧金山市中心：
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
结果包含在 suggestions 数组中：
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
使用 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
现在，结果中包含更多内容，包括 5, 000 米半径范围之外的结果：
{ "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" ] } }, ... ] }
您还可以使用 locationBias 将搜索偏向矩形视口。以下示例将请求限制为旧金山市中心：
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-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": [ "point_of_interest", "store", "establishment" ] } }, { "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": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
使用 includedPrimaryTypes
使用 includedPrimaryTypes 参数最多可指定表 A、表 B 中的五个类型值，或仅指定 (regions)，或仅指定 (cities)。地点必须与指定的主要类型值之一匹配，才能包含在响应中。
在以下示例中，您指定 input 字符串“Soccer”，并使用 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 字段，其中包含推荐的文本搜索字符串。您可以发出文本搜索（新版）请求，以详细了解返回的任何联想查询。
使用源站
在此示例中，在请求中添加 origin 作为纬度和经度坐标。添加 origin 后，自动补全（新版）会在响应中添加 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 } } ] }
查找未来开业的商家
以下示例展示了针对爱达荷州新梅多斯未来开业商家的自动补全（新版）请求：
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"input": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:autocomplete"
回答包含有关该地点的详细信息，但不包含开业日期。
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do", "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "text": { "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA", "matches": [ { "endOffset": 32 } ] }, "structuredFormat": { "mainText": { "text": "Roberts Greenhouse and Tree Farm", "matches": [ { "endOffset": 32 } ] }, "secondaryText": { "text": "McLain Street, New Meadows, ID, USA" } }, "types": [ "garden_center", "establishment", "service", "store", "point_of_interest" ] } } ] }
响应中缺少距离
在某些情况下，即使请求中包含 origin，响应正文中也会缺少 distanceMeters。在以下情况下可能会发生这种情况：
route预测不包含distanceMeters。- 当
distanceMeters的值为0时，系统不会添加该字段，对于距离提供的origin位置不到 1 米的预测结果，就会出现这种情况。
尝试从解析的对象中读取 distanceMeters 字段的客户端库将返回值为 0 的字段。为避免误导用户，请勿向用户显示零距离。
自动补全（新版）优化
本部分介绍了帮助您充分利用 Autocomplete（新版）服务的最佳实践。
下面列出了一些一般准则：
- 若要开发可正常运行的界面，最快的方式是使用 Maps JavaScript API Autocomplete（新版）widget、Places SDK for Android Autocomplete（新版）widget 或 Places SDK for iOS Autocomplete（新版）widget。
- 从一开始就了解重要的 Autocomplete (New) 数据字段。
- 位置自定义调整和位置限制字段是可选的，但可能会对自动补全性能产生重大影响。
- 使用错误处理可确保您的应用在 API 返回错误时妥善降级。
- 请确保您的应用可以处理没有选择任何内容的情况，并能够让用户继续操作。
费用优化最佳实践
基本费用优化
为了优化 Autocomplete（新版）服务的使用费用，请在地点详情（新版）和 Autocomplete（新版）微件中使用字段掩码，以便仅返回所需的 Autocomplete（新版）数据字段。
高级费用优化
请考虑通过程序化方式实现自动补全（新版），以便采用 SKU：自动补全请求定价模式，并请求关于所选地点（而不是地点详情 [新版]）的 Geocoding API 结果。如果同时满足以下两个条件，与采用“按会话”（基于会话）定价模式相比，将“按请求”定价模式与 Geocoding API 搭配使用的性价比更高：
- 如果您只需要用户所选地点的纬度和经度或地址，那么采用 Geocoding API 提供此类信息所需的费用会低于调用地点详情（新版）。
- 如果用户平均在不超过四次自动补全（新版）联想查询请求之内选择自动补全联想查询结果，那么“按请求”定价模式可能会比“按会话”定价模式的性价比更高。
| 您的应用需要什么 | 用户选择预测结果之前平均发出的自动补全（新版）请求数 | 推荐的实现方式 |
|---|---|---|
| 地址和位置以外的地点详情，例如地点名称、营业状态或营业时间 | 数量不限 | 基于会话的自动补全（新版）与地点详情（新版） |
| 仅所选预测结果的地址和纬度/经度 | 4 根或更少 | 按请求计费的 Autocomplete（新版）与 Geocoding API |
| 仅所选预测结果的地址和纬度/经度 | 超过 4 个 | 适用于仅地址应用的基于会话的自动补全（新版） |
对于您的应用，Geocoding API 可能比地点详情 (New) 性价比更高，具体取决于您使用 Autocomplete (New) 的性能。每个应用的自动补全（新版）效率各有不同，具体取决于用户输入的内容、使用应用所在的位置，以及是否遵循了性能优化最佳实践。
如需确定表格中的平均请求数，请分析用户在您的应用中选择自动补全（新版）预测结果之前平均会输入多少个字符。
基于会话的自动补全（新版）与地点详情（新版）
将基于会话的自动补全（新版）与地点详情（新版）搭配使用。
由于您的应用需要地点详情（新版），例如地点名称、营业状态或营业时间，因此您实现的自动补全（新版）应使用会话令牌（以编程方式或内置于 JavaScript、Android 或 iOS widget 中），按会话加上适用的地点 SKU 计费，具体取决于您请求的地点数据字段。1
widget 实现
会话管理功能自动内置于 JavaScript、Android 或 iOS widget 中。这包括针对所选预测结果的“自动补全（新版）”请求和“地点详情（新版）”请求。请务必指定 fields 参数，以确保您只请求所需的 Autocomplete（新版）数据字段。
程序化实现
在“自动补全（新版）”请求中使用会话令牌。在请求关于所选预测结果的地点详情（新版）时，添加以下参数：
- “自动补全（新版）”响应中的地点 ID
- “自动补全（新版）”请求中使用的会话令牌
fields参数，用于指定您所需的自动补全（新版）数据字段
按请求 Autocomplete（新版）与 Geocoding API
在不使用会话令牌的情况下以程序化方式实现自动补全（新版），并针对所选的地点预测调用 Geocoding API。
Geocoding API 提供地址和纬度/经度坐标。
发出四次自动补全请求加上针对所选地点预测调用 Geocoding API 的总费用低于按会话结算的自动补全（新版）价格（即每次会话的价格）。1
您可以考虑采用性能最佳实践，帮助用户以更少的字符找到所需的预测结果。
适用于仅地址应用的基于会话的 Autocomplete（新版）
将基于会话的自动补全（新版）与地点详情（新版）搭配使用。
由于您预计在用户选择“自动补全（新版）”预测结果之前发出的平均请求数超过了按会话定价的费用，因此您的“自动补全（新版）”实现应同时为“自动补全（新版）”请求和关联的“地点详情（新版）”请求使用会话令牌
按会话。
1
widget 实现
会话管理功能自动内置于 JavaScript、Android 或 iOS widget 中。这包括针对所选预测结果的“自动补全（新版）”请求和“地点详情（新版）”请求。请务必指定 fields 参数，以确保您只请求所需的字段。
程序化实现
在“自动补全（新版）”请求中使用会话令牌。
在请求关于所选预测结果的地点详情（新版）时，添加以下参数：
- “自动补全（新版）”响应中的地点 ID
- “自动补全（新版）”请求中使用的会话令牌
fields参数，用于指定地址和几何图形等字段
考虑延迟自动补全（新版）请求
您可以采取一些策略，例如延迟自动补全（新版）请求，直到用户输入前三个或四个字符，从而减少应用发出的请求数量。例如，在用户输入第三个字符之后，针对每个字符发出 Autocomplete (New) 请求，这意味着如果用户输入七个字符，然后选择一个预测结果，您针对该预测结果发出一个 Geocoding API 请求，则总费用将为 4 次 Autocomplete (New) 按请求结算 + 地理编码。1
如果延迟请求会导致平均程序化请求次数低于四次，您可以按照使用 Geocoding API 提高自动补全（新版）性能的实现指南操作。请注意，如果用户希望每次输入新的字符后都能看到预测结果，可能会将延迟请求视为时间上的延迟。
您可以考虑采用性能最佳实践，帮助用户以较少的字符找到所需的预测结果。
-
如需了解费用，请参阅 Google Maps Platform 价格表。
性能最佳实践
下面的指南介绍了优化自动补全（新版）性能的方式：
- 向自动补全（新版）实现添加国家/地区限制、位置自定义调整和语言偏好设置（适用于程序化实现）。您无需为 widget 进行语言偏好设置，因为它们会从用户的浏览器或移动设备中选择语言偏好设置。
- 如果自动补全（新版）附有地图，您可以根据地图视口来设置位置偏向。
- 如果用户未选择任一 Autocomplete (New) 预测结果，通常是因为这些预测结果都不是所需的结果地址，您可以重复使用原始用户输入来尝试获取更相关的结果：
- 如果您希望用户仅输入地址信息，请在调用 Geocoding API 时重复使用原始用户输入。
- 如果您希望用户按名称或地址查询某个地点，请使用“地点详情（新版）”请求。如果希望仅显示特定区域内的结果，请使用位置自定义调整。
- 用户输入子场所地址，例如建筑物内特定单元或公寓的地址。例如，捷克地址“Stroupežnického 3191/17, Praha”会在自动补全（新版）中生成部分预测结果。
- 用户在输入地址时，需要输入路段前缀，例如纽约的“23-30 29th St, Queens”或夏威夷考爱岛“47-380 Kamehameha Hwy, Kaneohe”。
位置信息偏向
通过传递 location 参数和 radius 参数，使结果偏向指定区域。这会指示自动补全（新版）优先显示指定区域内的结果。指定区域以外的结果可能仍会显示。您可以使用 includedRegionCodes 参数过滤结果，以便仅显示指定国家/地区内的地点。
位置限制
通过传递 locationRestriction 参数，将结果限制在指定区域内。
您还可以添加 locationRestriction 参数，将结果限制在由 location 和 radius 参数定义的区域内。这会指示自动补全（新版）仅返回该区域内的结果。
试试看！
借助 APIs Explorer，您可以发出示例请求，以便熟悉 API 和 API 选项。
选择页面右侧的 API 图标 api。
（可选）修改请求参数。
选择执行按钮。在对话框中，选择要用于发出请求的账号。
在 APIs Explorer 面板中，选择全屏图标 fullscreen 以展开 APIs Explorer 窗口。