此页面由 Cloud Translation API 翻译。

地点自动补全（新）

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

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

自动补全（新）服务可以按完整词语和子字符串，解析地点名称、地址和加号代码。因此，应用能够以用户的身份类型，以便即时提供地点建议。

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

例如，您可以使用一个包含部分内容的字符串作为输入来调用 API 输入“Spagh”，将搜索区域限定为纽约市。然后，响应会包含与搜索条件匹配的地点建议列表字符串和搜索区域，例如名为“Cafe Spaghetti”的餐厅以及该地点的详细信息

系统会向用户显示返回的地点建议 以便选择所需的地点您可以创建地点详情（新）请求以获取更多返回的任何地点建议的相关信息。

“自动补全（新）”请求

通过对 GMSPlaceClient。您可以在 GMSAutocompleteRequest 对象。该响应在 GMSAutocompletePlaceSuggestion 对象。

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

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

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

Places Swift SDK for iOS（预览版）

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。通过自动补全（新）服务会返回候选匹配结果并根据此字符串对结果进行排序。

可选参数

类型

一个地点只能有一种主要类型 Table A 或 Table B。例如，主要类型可能是 mexican_restaurant 或 steak_house。

默认情况下，该 API 会根据 input 参数返回所有地点，而不考虑与地点关联的主要类型值。限制结果特定主要类型或主要类型 types 参数。

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

如果出现以下情况，则请求将被拒绝并出现 INVALID_REQUEST 错误：

指定了超过五种类型。
指定了所有无法识别的类型。

国家/地区

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

Swift

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

Objective-C

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

Places Swift SDK for iOS（预览版）

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。对于 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);

Places Swift SDK for iOS（预览版）

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

矩形是一种经纬度视口，表示为位于low和high点对面。视口被视为封闭区域这意味着它包含其边界。纬度边界必须在 -90 到 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.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);

Places Swift SDK for iOS（预览版）

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

Places Swift SDK for iOS（预览版）

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

regionCode

用于设置响应格式的地区代码，指定为 ccTLD（“顶级 domain”）两个字符的值。大多数 ccTLD 代码都与 ISO 3166-1 代码相同，一些值得注意的例外情况。例如，英国的 ccTLD 为“uk” (.co.uk)，而其 ISO 3166-1 代码为“gb”（技术上适用于“ 英国”）。

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

sessionToken

会话令牌是用户生成的字符串，用于跟踪将“自动补全（新）”调用作为“会话”调用。自动补全（新）使用会话令牌用户自动补全搜索到离散会话的查询和选择阶段用于结算目的有关详情，请参阅会话令牌。

自动补全（新）示例

使用 locationRestriction 和 locationBias

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

位置限制用于指定要搜索的区域。指定范围以外的结果不会返回任何区域。以下示例使用位置限制来限制对以 5000 米半径为中心的圆形位置限制的请求旧金山：

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 for iOS（预览版）

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

Places Swift SDK for iOS（预览版）

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

Places Swift SDK for iOS（预览版）

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

Places Swift SDK for iOS（预览版）

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 徽标 field/results.有关详情，请参阅显示 Google 徽标和提供方说明。