自动补全（新）服务是一种 iOS API，可返回地点建议以响应请求。在请求中，指定文本搜索字符串和用于控制搜索区域的地理边界。
自动补全（新）服务可以根据输入的完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Codes。这样，应用就可以在用户输入内容时发送查询，从而即时提供地点建议。
地点建议是指根据指定的输入文本字符串和搜索区域提供的地点（例如商家、地址和地图注点）。
例如，您调用 API 时，输入包含部分用户输入内容“Spagh”的字符串，并将搜索区域限制为纽约市。然后，响应会包含与搜索字符串和搜索区域匹配的地点建议列表，例如名为“Cafe Spaghetti”的餐厅，以及有关该地点的详细信息。
返回的地点建议旨在向用户展示，以便用户可以选择所需的地点。您可以发出地点详情（新）请求，以获取有关任何返回的地点建议的更多信息。
您可以通过以下两种主要方式将自动补全（新）功能集成到您的应用中：
- 以编程方式获取地点预测结果：直接调用 API 以检索预测结果，并在自定义用户界面中显示这些结果。
- 添加地点自动补全 widget：提供即用型搜索自动补全体验，可在用户输入内容时显示预测结果。
以编程方式获取地点预测结果
自动补全（新）请求
通过调用 GMSPlacesClient 上的方法来创建自动补全请求。
您可以在 GMSAutocompleteRequest 对象中传递参数。响应会在 GMSAutocompletePlaceSuggestion 对象中提供自动补全建议。
必须提供 API 密钥和 query 参数。您还可以添加 GMSAutocompleteSessionToken 将请求与结算会话相关联，并添加 GMSAutocompleteFilter 以应用于结果。
Places Swift SDK 版本
通过调用 PlacesClient 上的方法来创建自动补全请求。
您可以在 AutocompleteRequest 对象中传递参数。响应会在 AutocompletePlaceSuggestion 对象中提供自动补全建议。
必须提供 API 密钥和 query 参数。您还可以添加 AutocompleteSessionToken 将请求与结算会话相关联，并添加 AutocompleteFilter 以应用于结果。
如需详细了解必需参数和可选参数，请参阅本文档的“参数”部分。
Places Swift SDK
let center = (37.3913916, -122.0879074) let northEast = (37.388162, -122.088137) let southWest = (37.395804, -122.077023) let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest) let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias) let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): // Handle suggestions. case .failure(let placesError): // Handle error. }
Swift
let token = GMSAutocompleteSessionToken() let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051) let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087) let filter = GMSAutocompleteFilter() filter.types = [kGMSPlaceTypeRestaurant] filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds) let request = GMSAutocompleteRequest(query:"Spagh") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137); CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023); GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ kGMSPlaceTypeRestaurant ]; filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest); GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
自动补全（新）响应
自动补全功能会返回一个最多包含 5 个 GMSAutocompleteSuggestion 实例的数组。该数组包含：
placeIDtypes：适用于相应地点的类型。distanceMeters：与原点的距离。attributedFullText：建议的完整直观易懂的文本。attributedPrimaryText：建议的直观易懂的主要文本。attributedSecondaryText：建议的易于理解的辅助文本。structuredFormat：具体名称和消歧文本，例如城市或地区。
必需参数
查询
要搜索的文本字符串。指定完整字词和子字符串、地点名称、地址和 Plus Codes。自动补全（新）服务将根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。
可选参数
sessionToken
会话令牌是用户生成的字符串，用于将自动补全（新）调用（包括通过 widget 进行的调用和程序化调用）跟踪为“会话”。自动补全（新）使用会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。
您可以公开地点自动补全会话令牌，以便将其传递给不属于 Places SDK for iOS 的其他服务，例如地址验证：
Places Swift SDK
let token = AutocompleteSessionToken() let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5)) let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter) PlacesClient.shared.fetchAutocompleteSuggestions(request: request) { case .success(let suggestions): ... case .failure(let placesError): print(placesError) } // pass token's string format to use with a service that is not a part of iOS SDK. print("token: \(token)")
Objective-C
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"]; GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init]; request.sessionToken = token; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5]; filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation); request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results, NSError *_Nullable error) { ... }]; // pass token's string format to use with a service that is not a part of iOS SDK. NSLog(@"%@", token.description);
如需了解详情，请参阅会话令牌。
可选的 AutocompleteFilter 参数
类型
一个地点只能有一个关联的主要类型（来自表 A 或表 B）。例如，主要类型可以是 mexican_restaurant 或 steak_house。
默认情况下，该 API 会根据 input 参数返回所有地点，而无需考虑与地点关联的主要类型值。通过传递 types 参数，将结果限制为特定主要类型或主要类型。
使用此参数可指定表 A 或表 B 中的最多五个类型值。地点必须与指定的主类型值之一匹配，才能包含在响应中。
如果出现以下情况，请求会被拒绝并显示 INVALID_REQUEST 错误：
- 指定了超过五种类型。
- 指定了任何无法识别的类型。
例如，如需将结果限制为体育用品商店，请在 AutocompleteFilter 中指定该类型：
Places Swift SDK
let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
Swift
let filter = GMSAutocompleteFilter() filter.types = ["sporting_goods_store"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ "sporting_goods_store" ];
国家/地区
仅包含指定地区列表中的结果，以数组形式指定，最多包含 15 个 ccTLD（“顶级域名”）双字符值。如果省略，则对响应不应用任何限制。 例如，如需将区域限制为德国和法国，请执行以下操作：
Places Swift SDK
let filter = AutocompleteFilter(countries: ["DE", "FR"])
Swift
let filter = GMSAutocompleteFilter() filter.countries = ["DE", "FR"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.countries = @[ @"DE", @"FR" ];
如果您同时指定了 locationRestriction 和 countries，则结果位于这两个设置的交集区域。
inputOffset
从零开始的 Unicode 字符偏移量，用于指示 input 中的光标位置。光标位置可能会影响返回的预测结果。如果为空，则默认为 input 的长度。
locationBias 或 locationRestriction
您可以指定 locationBias 或 locationRestriction，但不能同时指定这两者，以定义搜索区域。您可以将 locationRestriction 视为指定结果必须位于的区域，而将 locationBias 视为指定结果必须靠近但可以位于该区域之外的区域。
locationBias用于指定搜索区域。此位置用作偏差，这意味着系统可能会返回指定位置附近的结果，包括指定区域之外的结果。locationRestriction用于指定搜索区域。系统不会返回指定区域以外的结果。
将 locationBias 或 locationRestriction 区域指定为矩形视口或圆形视口。
圆由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含边界值）。默认值为 0.0。对于 locationRestriction，您必须将半径设置为大于 0.0 的值。否则，请求不会返回任何结果。
例如：
Places Swift SDK
let center = CLLocationCoordinate2DMake(40.477398, -74.259087) let bias = CircularCoordinateRegion(center: center, radius: 1000.0) let filter = AutocompleteFilter(coordinateRegionBias: bias)
Swift
let center = CLLocationCoordinate2DMake(40.730610, -73.935242) let radius = 1000.0 filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
Objective-C
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242); radius = 1000.0; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
矩形是一个经纬度视口，以两个对角相对的 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 都必须填充，并且所表示的框不能为空。空视口会导致错误。
例如，此视口完全包含纽约市：
Places Swift SDK
let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087) let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051) let filter = AutocompleteFilter(coordinateRegionBias: bias)
Swift
let high = CLLocationCoordinate2DMake(40.921628, -73.700051) let low = CLLocationCoordinate2DMake(40.477398, -74.259087) let filter = GMSAutocompleteFilter() filter.locationBias = GMSPlaceRectangularLocationOption(high, low)
Objective-C
CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087); CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051); GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationBias = GMSPlaceRectangularLocationOption(high, low);
源
用于计算到目的地的直线距离（以 distanceMeters 形式返回）的起点。如果省略此值，则不会返回直线距离。必须指定为纬度和经度坐标：
Places Swift SDK
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
Swift
let filter = GMSAutocompleteFilter() filter.origin = CLLocation(latitude: 37.395804, longitude: -122.077023)
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];
regionCode
用于设置响应格式的地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（代表“大不列颠及北爱尔兰联合王国”）。
如果您指定的区域代码无效，API 会返回 INVALID_ARGUMENT 错误。此参数可能会根据适用法律影响结果。
shouldIncludePureServiceAreaBusinesses
如果为 true，则在响应数组中返回纯上门服务商家。纯上门服务商家是指为客户送货上门或提供上门服务，但不在自己的商家地址为客户提供服务的商家。
例如：
Places Swift SDK
let filter = AutocompleteFilter() filter.shouldIncludePureServiceAreaBusinesses = true
Swift
let filter = AutocompleteFilter() filter.shouldIncludePureServiceAreaBusinesses = true
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.shouldIncludePureServiceAreaBusinesses = YES;
添加地点自动补全 widget
为了更轻松地提供一致的地点自动补全体验，您可以向应用中添加地点自动补全 widget。该 widget 提供了一个专用全屏界面，用于处理用户输入内容并向用户显示地点预测结果，同时向应用返回 AutocompletePlaceSuggestion 对象。然后，您可以发出地点详情（新）请求，以获取有关任何地点预测结果的更多信息。
与以程序化方式获取地点预测结果类似，地点自动补全 widget 可让您使用会话令牌将自动补全请求分组到会话中，以便进行结算。您可以通过调用 AutocompleteSessionToken() 传递会话令牌。
如果您未提供会话令牌，该 widget 将为您创建一个自动补全会话令牌，然后可以从 onSelection 回调中获取该令牌。如需详细了解如何使用会话令牌，请参阅关于会话令牌。
当 show 绑定值设置为 true 时，系统会将用户带到全屏视图，用户可以在其中选择地点。当用户输入内容时，该 widget 会返回地点建议，例如商家、地址和地图注点。当用户选择某个地点时，微件会使用所选地点调用 onSelection 处理程序，并关闭全屏视图。
地点自动补全 widget 参数
除了可通过编程方式使用的参数之外，地点自动补全 widget 还提供以下参数。
显示
show 用于指定是否显示 widget。
onSelection
选择地点时要运行的闭包。
onError
发生错误时要运行的闭包。如果发生错误，系统会传递 PlacesError。
内容和主题自定义
AutocompleteUICustomization 参数指定要应用于 widget 的界面自定义设置。自定义选项包括：
AutocompleteListDensity。 此参数可让您选择建议列表的密度，即multiLine或twoLine。AutocompleteUIIcon。此参数用于选择是否显示每个列表项的默认图标。theme。此参数用于指定可替换任何默认样式属性的自定义主题。您可以自定义地点自动补全组件的颜色、排版、间距、边框和圆角。默认值为PlacesMaterialTheme。未被覆盖的任何主题属性都使用默认样式。
自动补全（新）示例
使用 locationRestriction 和 locationBias
自动补全（新）默认使用 IP 偏向来控制搜索区域。借助 IP 偏向，API 会使用设备的 IP 地址来偏向结果。您可以视需要使用 locationRestriction 或 locationBias（但不能同时使用这两者）来指定要搜索的区域。
位置限制用于指定搜索区域。系统不会返回指定区域以外的结果。以下示例使用位置限制将请求限制为以旧金山为中心、半径为 5,000 米的圆形位置限制：
Places Swift SDK
let center = (37.775061, -122.419400) let radius = 5000.0 let restriction = CircularCoordinateRegion(center: center, radius: radius) let filter = AutocompleteFilter(coordinateRegionRestriction: restriction) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Swift
let token = GMSAutocompleteSessionToken() let center = CLLocationCoordinate2DMake(37.775061, -122.419400) let radius = 5000.0 let filter = GMSAutocompleteFilter() filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius) let request = GMSAutocompleteRequest(query:"Piz") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400); radius = 5000.0; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius); GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
使用位置偏差时，位置会作为偏差，这意味着系统可能会返回指定位置附近的结果，包括指定区域之外的结果。以下示例将之前的请求更改为使用位置偏差：
Places Swift SDK
let center = (37.775061, -122.419400) let radius = 5000.0 let bias = CircularCoordinateRegion(center: center, radius: radius) let filter = AutocompleteFilter(coordinateRegionBias: bias) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Swift
let token = GMSAutocompleteSessionToken() let center = CLLocationCoordinate2DMake(37.775061, -122.419400) let radius = 5000.0 let filter = GMSAutocompleteFilter() filter.locationBias = GMSPlaceCircularLocationOption(center, radius) let request = GMSAutocompleteRequest(query:"Piz") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400); radius = 5000.0; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationBias = GMSPlaceCircularLocationOption(center, radius); GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
使用类型
使用 types 参数可将请求的结果限定为表 A 和表 B 中列出的特定类型。您可以指定一个最多包含 5 个值的数组。如果省略，则返回所有类型。
以下示例指定了“Soccer”的查询字符串，并使用 types 参数将结果限制为 "sporting_goods_store" 类型的场所：
Places Swift SDK
let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ]) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Swift
let token = GMSAutocompleteSessionToken() let filter = GMSAutocompleteFilter() filter.types = ["sporting_goods_store"] let request = GMSAutocompleteRequest(query:"Soccer") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ "sporting_goods_store" ]; GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
使用来源
如果您在请求中添加 origin 参数（指定为纬度和经度坐标），API 会在响应中添加从出发地到目的地的直线距离。响应会返回距离，即 distanceMeters。
此示例将原点设置为旧金山的中心：
Places Swift SDK
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194)) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Swift
let token = GMSAutocompleteSessionToken() let origin = CLLocation(latitude: 37.7749, longitude: -122.4194) let filter = GMSAutocompleteFilter() filter.origin = origin let request = GMSAutocompleteRequest(query:"Amoeba") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))") } } })
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023]; GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
自定义内容和主题
Swift
let uiCustomization = AutocompleteUICustomization( listDensity: .multiLine, listItemIcon: .noIcon, theme: PlacesMaterialTheme() )
添加地点自动补全 widget（完整代码）
Places Swift SDK
struct PlaceAutocompleteDemoView: View { @State private var fetchedPlace: Place? @State private var placesError: PlacesError? @State private var showWidget = false public var body: some View { VStack { Button("Search for a place") { showWidget.toggle() } .placeAutocomplete( show: $showWidget, onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in Task { let placesClient = await PlacesClient.shared let fetchPlaceRequest = FetchPlaceRequest( placeID: autocompletePlaceSuggestion.placeID, placeProperties: [.displayName, .formattedAddress], sessionToken: autocompleteSessionToken ) switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): print("Fetched place: \(place)") self.fetchedPlace = place case .failure(let placesError): print("Failed to fetch place: \(placesError)") self.placesError = placesError } } }, onError: { placesError in self.placesError = placesError } ) } } }
自动补全（新）优化
本部分介绍了帮助您充分利用自动补全（新）服务的最佳实践。
下面列出了一些一般准则：
- 若要开发可正常运行的界面，最快的方式是使用 Maps JavaScript API Autocomplete (New) widget、Places SDK for Android Autocomplete (New) widget 或 Places SDK for iOS Autocomplete (New) widget。
- 从一开始就了解重要的自动补全（新）数据字段。
- 位置自定义调整和位置限制字段是可选的，但可能会对自动补全性能产生重大影响。
- 使用错误处理可确保您的应用在 API 返回错误时妥善降级。
- 请确保您的应用可以处理没有选择任何内容的情况，并能够让用户继续操作。
费用优化最佳实践
基本费用优化
为了优化自动补全（新）服务的使用费用，请在地点详情（新）和自动补全（新）widget 中使用字段掩码，以便仅返回所需的自动补全（新）数据字段。
高级费用优化
请考虑通过程序化方式实现自动补全（新），以便采用“自动补全请求”SKU 定价，并请求关于所选地点（而不是地点详情 [新]）的 Geocoding API 结果。如果同时满足以下两个条件，与采用“按会话”（基于会话）定价模式相比，将“按请求”定价模式与 Geocoding API 搭配使用的性价比更高：
- 如果您只需要用户所选地点的纬度/经度或地址，那么采用 Geocoding API 提供此类信息所需的费用会低于调用地点详情（新）所需的费用。
- 如果用户平均在不超过四次自动补全（新）预测请求之内选择自动补全预测结果，那么“按请求”定价模式可能会比“按会话”定价模式的性价比更高。
除了所选预测结果的地址和纬度/经度外，您的应用是否需要任何其他信息？
是，需要更多详细信息
将基于会话的自动补全（新）与地点详情（新）搭配使用。
由于您的应用需要地点详情（新），例如地点名称、营业状态或营业时间，因此您在实现自动补全（新）时应使用会话令牌（以编程方式或内置于 JavaScript、Android 或 iOS widget 中），每个会话一个令牌，并根据您请求的地点数据字段支付适用的 Places SKU 费用。1
widget 实现
会话管理功能自动内置于
JavaScript、
Android 或 iOS
widget 中。这包括针对所选预测结果的“自动补全（新）”请求和“地点详情（新）”请求。请务必指定 fields 参数，以确保您只请求所需的自动补全（新）数据字段。
程序化实现
在自动补全（新）请求中使用会话令牌。在请求关于所选预测结果的地点详情（新）时，添加以下参数：
否，只需要地址和位置信息
对于您的应用，Geocoding API 可能比地点详情（新）性价比更高，具体取决于您使用自动补全（新）的性能。每个应用的自动补全（新）效率各有不同，具体取决于用户输入的内容、使用应用所在的位置，以及是否遵循了性能优化最佳实践。
为了回答以下问题，请分析用户在您的应用中选择自动补全（新）预测结果之前平均会输入多少个字符。
平均而言，用户是否能够在不超过四次请求之内选择自动补全（新）预测结果？
是
在不使用会话令牌的情况下以程序化方式实现自动补全（新），并针对所选的地点预测调用 Geocoding API。
Geocoding API 提供地址和纬度/经度坐标。
发出四次自动补全请求加上针对所选地点预测调用 Geocoding API 的费用低于按会话结算的自动补全（新）费用（按会话结算）。1
您可以考虑采用性能最佳实践，帮助用户以更少的字符找到所需的预测结果。
否
将基于会话的自动补全（新）与地点详情（新）搭配使用。
由于您预计在用户选择“自动补全（新）”预测结果之前发出的请求的平均数量超过了“按会话”定价的费用，因此您在实现“自动补全（新）”时应为“自动补全（新）”请求和关联的“地点详情（新）”请求使用会话令牌，以便采用按会话定价。
1
widget 实现
会话管理功能自动内置于
JavaScript、
Android 或 iOS
widget 中。这包括针对所选预测结果的“自动补全（新）”请求和“地点详情（新）”请求。请务必指定 fields 参数，以确保您只请求所需的字段。
程序化实现
在自动补全（新）请求中使用会话令牌。
在请求关于所选预测结果的地点详情（新）时，添加以下参数：
- 自动补全（新）响应中的地点 ID
- “自动补全（新）”请求中使用的会话令牌
fields参数，用于指定地址和几何图形等字段
考虑延迟“自动补全（新）”请求
您可以采取一些策略，例如延迟“自动补全（新）”请求，直到用户输入前三个或四个字符，从而减少应用发出的请求数量。例如，在用户输入第三个字符后，针对每个字符发出自动补全（新）请求，这意味着如果用户输入七个字符，然后选择一个预测结果，而您针对该预测结果发出一个 Geocoding API 请求，则总费用将为 4 次自动补全（新）按请求结算的费用 + Geocoding 费用。1
如果延迟请求会导致平均程序化请求次数低于四次，您可以按照使用 Geocoding API 提高自动补全（新）性能的实现指南操作。请注意，如果用户希望每次输入新的字符后都能看到预测结果，可能会将延迟请求视为时间上的延迟。
您可以考虑采用性能最佳实践，帮助用户以较少的字符找到所需的预测结果。
-
如需了解费用，请参阅 Google Maps Platform 价格表。
性能最佳实践
下面的指南介绍了优化自动补全（新）性能的方式：
- 向自动补全（新）实现添加国家/地区限制、位置自定义调整和语言偏好设置（适用于程序化实现）。您无需为 widget 进行语言偏好设置，因为它们会从用户的浏览器或移动设备中选择语言偏好设置。
- 如果自动补全（新）附有地图，您可以根据地图视口来设置位置偏向。
- 如果用户未选择任一自动补全（新）预测结果，通常是因为这些预测结果都不是所需的结果地址，您可以重复使用原始用户输入来尝试获取更相关的结果：
- 如果您希望用户仅输入地址信息，请在调用 Geocoding API 时重复使用原始用户输入。
- 如果您希望用户按名称或地址查询某个地点，请使用“地点详情（新）”请求。如果希望仅显示特定区域内的结果，请使用位置自定义调整。
- 输入子地址的用户，例如建筑物内特定单元或公寓的地址。例如，捷克地址“Stroupežnického 3191/17, Praha”会在自动补全（新）中生成部分预测结果。
- 用户在输入地址时，需要输入路段前缀，例如纽约的“23-30 29th St, Queens”或夏威夷考爱岛“47-380 Kamehameha Hwy, Kaneohe”。
位置信息偏差
通过传递 location 参数和 radius 参数，使结果偏向指定区域。这会指示自动补全（新）优先显示定义区域内的结果。指定区域以外的结果可能仍会显示。您可以使用 components 参数过滤结果，以仅显示指定国家/地区内的地点。
限制位置
通过传递 locationRestriction 参数，将结果限制在指定区域内。
您还可以添加 locationRestriction 参数，将结果限制为由 location 和 radius 参数定义的区域。这会指示自动补全（新）仅返回该区域内的结果。