地点自动补全（新）

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

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

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

例如，您使用包含部分用户输入的字符串“Sicilian piz”作为输入来调用 API，并且搜索区域限定为加利福尼亚州旧金山。然后，响应会包含与搜索字符串和搜索区域匹配的地点建议列表（例如名为“西西里披萨厨房”的餐厅）以及关于该地点的详细信息。

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

注意 ：您必须启用原始 Autocomplete API 才能使用 widget 功能。可以同时启用原始 API 和新 API。如需了解详情，请参阅地点自动补全（新）迁移指南。

自动补全（新）请求

通过对 GMSPlaceClient 调用一个方法来创建“自动补全”请求。您可以在 GMSAutocompleteRequest 对象中传递参数。响应会在 GMSAutocompletePlaceSuggestion 对象中提供自动补全建议。

API 密钥和 query 参数为必填项。您还可以添加 GMSAutocompleteSessionToken 以将请求与结算会话相关联，以及添加 GMSAutocompleteFilter 以应用于结果。

如需详细了解必需参数和可选参数，请参阅本文档的参数部分。

Swift

let token = GMSAutocompleteSessionToken()

let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

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

GooglePlacesSwift

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.
}

自动补全（新）响应

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

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

必需参数

个查询

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

可选参数

类型

一个地点只能具有与其关联的表 A 或表 B 类型的一个主要类型。 例如，主要类型可能是 mexican_restaurant 或 steak_house。

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

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

如果出现以下情况，请求会被拒绝并返回 INVALID_REQUEST 错误：

• 指定了超过五种类型。
• 指定了任何无法识别的类型。

国家/地区

仅包含指定区域列表中的结果，以最多包含 15 个 ccTLD（“顶级域名”）双字符值的数组指定。如果省略，则不会对响应应用任何限制。例如，要将区域限制为德国和法国：

Swift

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

GooglePlacesSwift

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

如果您同时指定 locationRestriction 和 countries，则结果位于这两项设置的交集区域中。

inputOffset

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

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 的值。否则，该请求不会返回任何结果。

例如：

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);

GooglePlacesSwift

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

矩形是一个经纬度视口，表示为两个对角线的 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 都必须填充，且表示的框不能为空。空视口会导致错误。

例如，以下视口可将纽约市完全包围：

Swift

let high = CLLocationCoordinate2DMake(40.477398, -74.259087)
let low = CLLocationCoordinate2DMake(40.921628, -73.700051)

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);

GooglePlacesSwift

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

发迹地

用于计算到目的地的直线距离的起点（返回为 distanceMeters）。如果省略此值，则不会返回直线距离。必须指定为纬度和经度坐标：

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];

GooglePlacesSwift

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude:  -122.077023))
  

regionCode

用于设置响应格式的地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。除了某些明显的例外情况之外，大多数 ccTLD 代码都与 ISO 3166-1 代码相同。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（专指“大不列颠及北爱尔兰联合王国”）。

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

sessionToken

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

自动补全（新）示例

使用 locationRestriction 和 locationBias

自动补全（新）默认使用 IP 自定义调整来控制搜索区域。通过 IP 自定义调整，API 使用设备的 IP 地址来自定义调整结果。您可以选择使用 locationRestriction 或 locationBias，但不能同时使用这两者，以指定要搜索的区域。

位置限制用于指定搜索区域。系统不会返回指定区域以外的结果。以下示例使用位置限制，将请求限制为以旧金山为中心且半径为 5,000 米的圆形位置限制：

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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
  })

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

GooglePlacesSwift

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.locationBias = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

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

GooglePlacesSwift

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.
}
  

使用类型

使用类型参数将请求的结果限制为特定类型，如表 A 和表 B 中所述。您可以指定最多包含五个值的数组。如果省略，则返回所有类型。

以下示例指定了查询字符串“Soccer”，并使用 types 参数将结果限制为 "sporting_goods_store" 类型的场所：

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
  // Handle response
})

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

GooglePlacesSwift

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.
}
    

使用来源

在请求中添加 origin 参数（指定为纬度和经度坐标）时，API 会在响应中包含从出发地到目的地的直线距离。响应以 distanceMeters 的形式返回距离。

以下示例将原点设置为旧金山的中心：

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
  // Handle response
})

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

GooglePlacesSwift

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.
}
  

归因

即使没有地图，您也可以使用自动补全（新）。如果您确实要显示地图，则必须使用 Google 地图。在不显示地图的情况下显示自动补全（新）服务提供的建议时，您必须添加内嵌在搜索字段/结果中显示的 Google 徽标。如需了解详情，请参阅显示 Google 徽标和提供方说明。