自动补全（新版）会返回地点预测结果，以响应包含文本搜索字符串和控制搜索区域的地理边界的请求。自动补全功能可以根据输入内容的完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Code。您的应用可以在用户输入内容时发送查询，从而即时进行地点和查询预测。
例如，您调用自动补全功能，并使用包含部分用户输入内容的字符串“Sicilian piz”作为输入，同时将搜索区域限制为加利福尼亚州旧金山。然后，响应会包含与搜索字符串和搜索区域匹配的联想查询地点列表，例如名为“Sicilian Pizza Kitchen”的餐厅。返回的联想地点旨在呈现给用户，以帮助他们选择所需地点。您可以发出地点详情（新版）请求，以获取有关任何返回的地点预测结果的更多信息。
您可以通过以下两种主要方式将自动补全（新版）功能集成到应用中：
- 添加地点自动补全 widget：通过
PlaceAutocomplete类提供即用型搜索自动补全体验，该类会在用户输入内容时显示联想查询。 - 以程序化方式获取地点联想查询：直接调用 API 以检索联想查询，并在自定义界面中显示这些联想查询。
添加地点自动补全 widget
为了更轻松地提供一致的地点自动补全体验，您可以向应用中添加地点自动补全 widget。该 widget 提供了一个专用全屏界面，可处理用户输入并向用户显示地点预测结果，同时向应用返回 AutocompletePrediction 对象。然后，您可以发出地点详情（新版）请求，以获取有关任何地点预测结果的更多信息。
与以程序化方式获取地点联想查询时一样，地点自动补全 widget 允许您使用会话令牌将自动补全请求分组到会话中，以便进行结算。您可以在为 widget 创建 intent 时通过调用 setAutocompleteSessionToken() 传递会话令牌。如果您未提供会话令牌，该 widget 会为您创建一个，您可以通过调用 getSessionTokenFromIntent() 来访问该令牌。如需详细了解如何使用会话令牌，请参阅会话令牌简介。
如需向应用添加地点自动补全 widget，请执行以下操作：
（可选）定义会话令牌。如果您未提供会话令牌，该 widget 会为您创建一个。
使用所需参数和会话令牌定义
autocompleteIntent。为
StartActivityForResult定义ActivityResultLauncher。此启动器将处理自动补全 activity 返回的结果。在
ActivityResultLauncher的回调中处理结果。这涉及 提取AutocompletePrediction和AutocompleteSessionToken（如果 您尚未提供自己的）、处理错误，以及视需要发出fetchPlace()请求以获取有关地点的更多详细信息。使用
placeAutocompleteActivityResultLauncher启动 intent
以下示例演示了如何使用 Kotlin 和 Java 添加地点自动补全 widget：
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
自定义主题
在实例化自动补全体验时，您可以指定一个主题，以替换任何默认样式属性。您可以自定义地点自动补全组件的颜色、排版、间距、边框和边角。默认值为 PlacesMaterialTheme。任何未被替换的主题属性都会使用默认样式。
您可以在 …/res/values/themes.xml 中定义主题替换。例如：
<?xml version="1.0" encoding="utf-8"?> <resources> <style name="BrandedTheme" parent="PlacesMaterialTheme"> <!-- Color tokens. --> <item name="placesColorOnNeutralContainer">#5300e8</item> <item name="placesColorOnNeutralContainerVariant">#ee6002</item> ... <!-- Typography tokens. --> <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item> <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item> ... <!-- Spacing tokens. --> <item name="placesSpacingSmall">6dp</item> <item name="placesSpacingMedium">12dp</item> ... <!-- Attribution tokens. --> <item name="placesColorAttributionLightTheme">white</item> <item name="placesColorAttributionDarkTheme">black</item> </style> </resources>
然后，您可以通过调用 setAutocompleteUiCustomization 来引用替换样式：
ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (intent != null) { AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent(intent); AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent(intent); Status status = PlaceAutocomplete.getResultStatusFromIntent(intent); ... } } } ); Intent placeAutocompleteIntent = new PlaceAutocomplete.IntentBuilder() .setInitialQuery("INSERT_QUERY_TEXT") .setOrigin(new LatLng(10.0, 10.0)) ... .setAutocompleteUiCustomization( AutocompleteUiCustomization.builder() .listItemIcon(AutocompleteUiIcon.noIcon()) .listDensity(AutocompleteListDensity.MULTI_LINE) .theme(R.style.BrandedTheme) .build()) .build(this); placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);
以编程方式获取地点联想查询
您的应用可以通过调用 PlacesClient.findAutocompletePredictions() 并传递 FindAutocompletePredictionsRequest 对象，从自动补全 API 获取预测的地点名称和/或地址列表。以下示例展示了对 PlacesClient.findAutocompletePredictions() 的完整调用。
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Sicilian piz")
.setRegionCode("ES")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);自动补全（新版）响应
此 API 会在 Task 中返回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含一个最多有五个 AutocompletePrediction 对象的列表，这些对象表示预测的地点。如果没有与查询和过滤条件对应的已知地点，则列表可能为空。
对于每个预测的地点，您可以调用以下方法来检索地点详情：
getFullText(CharacterStyle)会返回地点说明的完整文本。这是主要文本和次要文本的组合。示例：“Eiffel Tower, Avenue Anatole France, Paris, France”。此外，您还可以使用此方法，通过CharacterStyle以您选择的样式突出显示说明中与搜索内容匹配的部分。CharacterStyle参数是可选的。如果您不需要任何突出显示，请将其设置为 null。getPrimaryText(CharacterStyle)会返回描述地点的正文。这通常是地点的名称。示例：“埃菲尔铁塔”和“123 Pitt Street”。getSecondaryText(CharacterStyle)会返回地点说明的辅助文本。例如，在显示自动补全联想查询时，这可用作第二行。示例：“Avenue Anatole France, Paris, France”和“Sydney, New South Wales”。getPlaceId()会返回预测地点的地点 ID。地点 ID 是唯一标识地点的文本标识符，您可以使用它在日后再次检索Place对象。如需详细了解自动补全中的地点 ID，请参阅地点详情（新版）。如需了解地点 ID 的一般信息，请参阅地点 ID 概览。getTypes()会返回与此地点关联的地点类型列表。getDistanceMeters()会返回此地点与请求中指定的起点之间的直线距离（以米为单位）。
必需参数
查询
用于进行搜索的文本字符串。指定完整字词和子字符串、地点名称、地址和 Plus Code。Autocomplete（新版）服务会根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。
如需设置查询参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setQuery() 方法。
可选参数
主要类型
一个列表，最多可包含表 A 或表 B 中的五个类型值，用于过滤响应中返回的地点。地点必须与指定的主要类型值之一匹配，才能包含在响应中。
一个地点只能有一个与其关联的表 A 或表 B 中的主要类型。例如，主要类型可能是 "mexican_restaurant" 或 "steak_house"。
如果出现以下情况，请求会被拒绝并显示 INVALID_REQUEST 错误：
- 指定了超过五种类型。
- 指定了任何无法识别的类型。
如需设置主要类型参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setTypesFilter() 方法。
国家/地区
仅包含指定国家/地区列表中的结果，该列表最多包含 15 个 ccTLD（“顶级域名”）双字符值。如果省略，则不会对回答应用任何限制。例如，如需将区域限制为德国和法国，请运行以下命令：
如果您同时指定了 locationRestriction 和 includedRegionCodes，则结果位于这两项设置的交集区域。
如需设置 countries 参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setCountries() 方法。
输入偏移量
从零开始的 Unicode 字符偏移量，用于指示查询中的光标位置。 光标位置可能会影响返回的联想查询。如果为空，则默认为查询的长度。
如需设置输入偏移量参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setInputOffset() 方法。
位置偏好或位置限制
您可以指定位置偏好或位置限制（但不能同时指定两者）来定义搜索区域。您可以将位置限制视为指定结果必须位于的区域，将位置偏好视为指定结果必须靠近的区域。关键区别在于，使用位置偏向时，系统可能仍会返回指定区域以外的结果。
位置信息偏好
指定要搜索的区域。此位置用作偏好设置，而非限制，因此系统可能仍会返回指定区域以外的结果。
如需设置位置偏向参数，请在构建
FindAutocompletePredictionsRequest对象时调用setLocationBias()方法。位置限制
指定要搜索的区域。系统不会返回指定区域以外的结果。
如需设置位置限制参数，请在构建
FindAutocompletePredictionsRequest对象时调用setLocationRestriction()方法。
将位置偏好或位置限制区域指定为矩形视口或圆形。
圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 到 50000.0 之间（含边界值）。默认值为 0.0。对于位置限制，您必须将半径设置为大于 0.0 的值。否则，请求不会返回任何结果。
矩形是一个经纬度视口，由两个对角相对的
low和high点表示。视口被视为封闭区域，这意味着它包含其边界。纬度边界必须介于 -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都必须填充，并且所表示的框不能为空。视口为空会导致错误。- 如果
来源
用于计算到目的地（使用 getDistanceMeters() 访问）的直线距离的起点。如果省略此值，系统将不会返回直线距离。必须指定为纬度和经度坐标：
如需设置 origin 参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setOrigin() 方法。
区域代码
用于设置响应格式（包括地址格式）的地区代码，指定为 ccTLD（“顶级域名”）双字符值。多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（代表“大不列颠及北爱尔兰联合王国”）。
如果您指定了无效的地区代码，API 会返回 INVALID_ARGUMENT 错误。该参数可能会根据适用法律影响结果。
如需设置地区代码参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setRegionCode() 方法。
会话令牌
会话令牌是用户生成的字符串，用于将自动补全（新版）调用（通过 widget 发出的调用和程序化调用）作为“会话”进行跟踪。“自动补全”使用会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。会话在用户开始输入查询内容时开始，并在用户选择地点时结束。在每个会话中，用户可以输入多项查询内容，并最终选择一个地点。会话结束后，令牌将失效；您的应用必须为每个会话生成一个新的令牌。我们建议您针对所有程序化自动补全会话使用会话令牌（当您嵌入 fragment 或使用 intent 启动自动补全时，API 会自动处理此问题）。
自动补全功能使用 AutocompleteSessionToken 来标识每个会话。您的应用应在每个新会话开始时传递一个新的会话令牌，然后在后续调用 fetchPlace() 时传递该令牌以及地点 ID，以检索用户所选地点的地点详情。
如需设置会话令牌参数，请在构建 FindAutocompletePredictionsRequest 对象时调用 setSessionToken() 方法。
如需了解详情，请参阅会话令牌。
自动补全（新版）示例
使用位置限制和位置偏好
自动补全（新版）默认使用 IP 偏向来控制搜索区域。使用 IP 偏向时，API 会使用设备的 IP 地址来偏向结果。您可以选择使用位置限制或位置偏好（但不能同时使用两者）来指定要搜索的区域。
位置限制用于指定要搜索的区域。系统不会返回指定区域以外的结果。以下示例使用位置限制，将请求限制在以旧金山为中心、半径为 5,000 米的圆形位置限制范围内：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);使用位置偏好设置时，位置会作为偏好设置，这意味着系统可以返回指定位置周围的结果，包括指定区域以外的结果。下一个示例将上一个请求更改为使用位置偏好：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);使用主要类型
使用 primary types 参数可将请求结果限制为表 A 和表 B 中列出的特定类型。您最多可以指定包含五个值的数组。如果省略，则系统会返回所有类型。
以下示例指定了查询字符串“Soccer”，并使用主要类型参数将结果限制为 "sporting_goods_store" 类型的场所：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Soccer")
.setIncludedPrimaryTypes(primaryTypes)
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);如果您省略主要类型参数，结果可能会包含您可能不想要的类型的场所，例如 "athletic_field"。
使用源站
当您在请求中添加 origin 参数（指定为经纬度坐标）时，API 会在响应中包含从起点到终点的直线距离（使用 getDistanceMeters() 访问）。以下示例将起点设置为旧金山的中心：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setOrigin(center)
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);自动补全（新版）优化
本部分介绍了帮助您充分利用 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 参数定义的区域内。这会指示自动补全（新版）仅返回该区域内的结果。