自动补全(新)服务是一种 iOS API,可在响应请求时返回地点建议。在请求中,指定控制搜索区域的文本搜索字符串和地理边界。
自动补全(新)服务可以匹配输入内容的全词和子字符串,从而解析地点名称、地址和 Plus Codes。因此,应用可以将查询作为用户类型发送,以即时提供地点建议。
地点建议是指根据指定的输入文本字符串和搜索区域进行的地点,例如商家、地址和地图注点。
例如,您可以使用包含部分用户输入的字符串“Sicilian piz”作为输入来调用 API,其中搜索区域仅限于加利福尼亚州旧金山。然后,响应中包含与搜索字符串和搜索区域匹配的一系列地点建议(例如名为“Sicilian Pizza Kitchen”的餐厅),以及该地点的详细信息。
系统会向用户显示返回的“地点建议”,以便用户选择所需的地点。您可以发出地点详情(新)请求,以获取有关返回的任何地点建议的更多信息。
“自动补全(新)”请求
对 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. }
自动补全(新)响应
自动补全功能会返回一个数组(最多包含 5 个 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
,用于指定要搜索的区域。指定区域以外的结果不会返回。
将 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”的查询字符串,并使用类型参数将结果限制为 "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 徽标和提供方说明。