地点自动补全（新）

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

欧洲经济区 (EEA) 开发者

自动补全（新版）服务是一种 iOS API，可根据请求返回地点建议。在请求中，指定文本搜索字符串和控制搜索区域的地理边界。

自动补全（新版）服务可以根据输入的完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Code。这样，应用就可以在用户输入内容时发送查询，从而即时进行地点建议。

地点建议是根据指定的输入文本字符串和搜索区域提供的地点，例如商家、地址和地图注点。

例如，您调用该 API，并使用包含部分用户输入“Spagh”的字符串作为输入，同时将搜索区域限制为纽约市。然后，响应会包含与搜索字符串和搜索区域匹配的地点建议列表，例如名为“Cafe Spaghetti”的餐厅，以及有关该地点的详细信息。

返回的地点建议旨在呈现给用户，以便他们选择所需地点。您可以发出地点详情（新版）请求，以详细了解返回的任何地点建议。

您可以通过以下两种主要方式将自动补全（新版）功能集成到应用中：

以编程方式获取地点联想查询

自动补全（新版）请求

通过对 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.
    }
  }
}];

自动补全（新版）响应

自动补全功能会返回一个最多包含五个 GMSAutocompleteSuggestion 实例的数组。该数组包含：

  • placeID
  • types：适用于此地点的类型。
  • distanceMeters：与原点的距离。
  • attributedFullText：建议的完整人类可读文本。
  • attributedPrimaryText：建议的主要文本，人类可读。
  • attributedSecondaryText：建议的人类可读次要文本。
  • structuredFormat：具体名称和消除歧义的文本，例如城市或区域。

必需参数

查询

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

可选参数

sessionToken

会话令牌是用户生成的字符串，用于将自动补全（新版）调用（通过 widget 发出的调用和程序化调用）作为“会话”进行跟踪。 Autocomplete（新版）使用会话令牌将用户自动补全搜索的查询和选择阶段归入不同的会话，以便进行结算。

您可以公开地点自动补全会话令牌，以便将其传递给不属于 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

与以程序化方式获取地点联想查询时一样，地点自动补全 widget 允许您使用会话令牌将自动补全请求分组到会话中，以便进行结算。您可以通过调用 AutocompleteSessionToken() 传递会话令牌。

如果您未提供会话令牌，该 widget 将为您创建一个自动补全会话令牌，然后您可以通过 onSelection 回调获取该令牌。如需详细了解如何使用会话令牌，请参阅会话令牌简介。

当 show 绑定值设置为 true 时，用户将进入全屏视图，并可在其中选择地点。当用户输入内容时，该 widget 会返回商家、地址和地图注点等地点的建议。当用户选择地点时，该 widget 会使用所选地点调用 onSelection 处理程序，并关闭全屏视图。

地点自动补全 widget 参数

除了可通过编程方式使用的参数之外，地点自动补全 widget 还提供以下参数。

显示

show 指定是否显示该微件。

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 中列出的特定类型。您最多可以指定包含五个值的数组。如果省略，则系统会返回所有类型。

以下示例指定了查询字符串“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
        }
      )
    }
  }
}

自动补全（新版）优化

本部分介绍了帮助您充分利用 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 提供此类信息所需的费用会低于调用地点详情（新版）。
  • 如果用户平均在不超过四次自动补全（新版）联想查询请求之内选择自动补全联想查询结果，那么“按请求”定价模式可能会比“按会话”定价模式的性价比更高。
如需选择对您的应用而言费用最低的 Autocomplete (New) 实现，请在下表中找到与您的应用需求相匹配的行。
您的应用需要什么 用户选择预测结果之前平均发出的自动补全（新版）请求数 推荐的实现方式
地址和位置以外的地点详情，例如地点名称、营业状态或营业时间 数量不限 基于会话的自动补全（新版）与地点详情（新版）
仅所选预测结果的地址和纬度/经度 4 根或更少 按请求计费的 Autocomplete（新版）与 Geocoding API
仅所选预测结果的地址和纬度/经度 超过 4 个 适用于仅地址应用的基于会话的自动补全（新版）

对于您的应用，Geocoding API 可能比地点详情 (New) 性价比更高，具体取决于您使用 Autocomplete (New) 的性能。每个应用的自动补全（新版）效率各有不同，具体取决于用户输入的内容、使用应用所在的位置，以及是否遵循了性能优化最佳实践。

如需确定表格中的平均请求数，请分析用户在您的应用中选择自动补全（新版）预测结果之前平均会输入多少个字符。

基于会话的自动补全（新版）与地点详情（新版）

将基于会话的自动补全（新版）与地点详情（新版）搭配使用。
由于您的应用需要地点详情（新版），例如地点名称、营业状态或营业时间，因此您实现的自动补全（新版）应使用会话令牌（以编程方式或内置于 JavaScript、Android 或 iOS widget 中），按会话加上适用的地点 SKU 计费，具体取决于您请求的地点数据字段。1

widget 实现
会话管理功能自动内置于 JavaScript、Android 或 iOS widget 中。这包括针对所选预测结果的“自动补全（新版）”请求和“地点详情（新版）”请求。请务必指定 fields 参数，以确保您只请求所需的 Autocomplete（新版）数据字段。

程序化实现
在“自动补全（新版）”请求中使用会话令牌。在请求关于所选预测结果的地点详情（新版）时，添加以下参数：

  1. “自动补全（新版）”响应中的地点 ID
  2. “自动补全（新版）”请求中使用的会话令牌
  3. fields 参数，用于指定您所需的自动补全（新版）数据字段

按请求 Autocomplete（新版）与 Geocoding API

在不使用会话令牌的情况下以程序化方式实现自动补全（新版），并针对所选的地点预测调用 Geocoding API。
Geocoding API 提供地址和纬度/经度坐标。 发出四次自动补全请求加上针对所选地点预测调用 Geocoding API 的总费用低于按会话结算的自动补全（新版）价格（即每次会话的价格）。1

您可以考虑采用性能最佳实践，帮助用户以更少的字符找到所需的预测结果。

适用于仅地址应用的基于会话的 Autocomplete（新版）

将基于会话的自动补全（新版）与地点详情（新版）搭配使用。
由于您预计在用户选择“自动补全（新版）”预测结果之前发出的平均请求数超过了按会话定价的费用，因此您的“自动补全（新版）”实现应同时为“自动补全（新版）”请求和关联的“地点详情（新版）”请求使用会话令牌 按会话。 1

widget 实现
会话管理功能自动内置于 JavaScript、Android 或 iOS widget 中。这包括针对所选预测结果的“自动补全（新版）”请求和“地点详情（新版）”请求。请务必指定 fields 参数，以确保您只请求所需的字段。

程序化实现
在“自动补全（新版）”请求中使用会话令牌。 在请求关于所选预测结果的地点详情（新版）时，添加以下参数：

  1. “自动补全（新版）”响应中的地点 ID
  2. “自动补全（新版）”请求中使用的会话令牌
  3. fields 参数，用于指定地址和几何图形等字段

考虑延迟自动补全（新版）请求
您可以采取一些策略，例如延迟自动补全（新版）请求，直到用户输入前三个或四个字符，从而减少应用发出的请求数量。例如，在用户输入第三个字符之后，针对每个字符发出 Autocomplete (New) 请求，这意味着如果用户输入七个字符，然后选择一个预测结果，您针对该预测结果发出一个 Geocoding API 请求，则总费用将为 4 次 Autocomplete (New) 按请求结算 + 地理编码。1

如果延迟请求会导致平均程序化请求次数低于四次，您可以按照使用 Geocoding API 提高自动补全（新版）性能的实现指南操作。请注意，如果用户希望每次输入新的字符后都能看到预测结果，可能会将延迟请求视为时间上的延迟。

您可以考虑采用性能最佳实践，帮助用户以较少的字符找到所需的预测结果。

  1. 如需了解费用，请参阅 Google Maps Platform 价格表。

性能最佳实践

下面的指南介绍了优化自动补全（新版）性能的方式：

  • 向自动补全（新版）实现添加国家/地区限制、位置自定义调整和语言偏好设置（适用于程序化实现）。您无需为 widget 进行语言偏好设置，因为它们会从用户的浏览器或移动设备中选择语言偏好设置。
  • 如果自动补全（新版）附有地图，您可以根据地图视口来设置位置偏向。
  • 如果用户未选择任一 Autocomplete (New) 预测结果，通常是因为这些预测结果都不是所需的结果地址，您可以重复使用原始用户输入来尝试获取更相关的结果：
    • 如果您希望用户仅输入地址信息，请在调用 Geocoding API 时重复使用原始用户输入。
    • 如果您希望用户按名称或地址查询某个地点，请使用“地点详情（新版）”请求。如果希望仅显示特定区域内的结果，请使用位置自定义调整。
    适合回退到 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 参数定义的区域内。这会指示自动补全（新版）仅返回该区域内的结果。