Place Autocomplete (New)

The Autocomplete (New) service is an iOS API that returns place suggestions in response to a request. In the request, specify a text search string and geographic bounds that controls the search area.

The Autocomplete (New) service can match on full words and substrings of the input, resolving place names, addresses, andplus codes.Applications can therefore send queries as the user types, to provide on-the-fly place suggestions.

Place suggestionsare places, such as businesses, addresses, and points of interest, based on the specified input text string and search area.

For example, you call the API using as input a string that contains a partial user input, "Sicilian piz", with the search area limited to San Francisco, CA. The response then contains a list ofplace suggestionsthat match the search string and search area, such as the restaurant named "Sicilian Pizza Kitchen", along with details about the place.

The returnedplace suggestionsare designed to be presented to the user so that they can select the desired place. You can make aPlace Details (New)request to get more information about any of the returned place suggestions.

Autocomplete (New) requests

Create an autocomplete request by calling a method on the GMSPlaceClient. You can pass parameters in the GMSAutocompleteRequest object. The response provides Autocomplete suggestions within a GMSAutocompletePlaceSuggestion object.

The API key andqueryparameters are required. You can also include GMSAutocompleteSessionToken to associate requests with a billing session and GMSAutocompleteFilter to apply to the results.

For more information about required and optional parameters, seethe parameters section of this document.

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

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

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

Autocomplete (New) responses

Autocomplete returns an array of up to five GMSAutocompleteSuggestioninstances. The array contains:

• placeID
• types:Types that apply to this place.
• distanceMeters:Distance from origin.
• attributedFullText:Full human-readable text of a suggestion.
• attributedPrimaryText:Human-readable primary text of a suggestion.
• attributedSecondaryText:Human-readable secondary text of a suggestion.
• structuredFormat:The specific name and disambiguating text, like city or region.

Required parameters

query

The text string on which to search. Specify full words and substrings, place names, addresses, andplus codes.The Autocomplete (New) service returns candidate matches based on this string and orders results based on their perceived relevance.

Optional parameters

types

A place can only have asingle primary typefrom typesTable AorTable Bassociated with it. For example, the primary type might bemexican_restaurantorsteak_house.

By default, the API returns all places based on theinputparameter, regardless of the primary type value associated with the place. Restrict results to be of a certain primary type or primary types by passing the typesparameter.

Use this parameter to specify up to five type values fromTable AorTable B.A place must match one of the specified primary type values to be included in the response.

The request is rejected with anINVALID_REQUESTerror if:

• More than five types are specified.
• Any unrecognized types are specified.

countries

Only include results from the list of specified regions, specified as an array of up to 15ccTLD ( "top-level domain" ) two-character values. If omitted, no restrictions are applied to the response. For example, to limit the regions to Germany and France:

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

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

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

If you specify bothlocationRestrictionandcountries,the results are located in the area of intersection of the two settings.

inputOffset

The zero-based Unicode character offset indicating the cursor position in input.The cursor position can influence what predictions are returned. If empty, it defaults to the length ofinput.

locationBias or locationRestriction

You can specifylocationBiasorlocationRestriction,but not both, to define the search area. Think oflocationRestrictionas specifying the region which the results must be within, andlocationBiasas specifying the region that the results must be near but can be outside of the area.

• locationBiasspecifies an area to search. This location serves as a bias, which means results around the specified location can be returned, including results outside the specified area.

• locationRestrictionspecifies an area to search. Results outside the specified area are not returned.

Specify thelocationBiasorlocationRestrictionregion as a rectangular viewport or as a circle.

A circle is defined by center point and radius in meters. The radius must be between 0.0 and 50000.0, inclusive. The default value is 0.0. For locationRestriction,you must set the radius to a value greater than 0.0. Otherwise, the request returns no results.

For example:

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

A rectangle is a latitude-longitude viewport, represented as two diagonally oppositelowandhighpoints. A viewport is considered a closed region, meaning it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive:

• Iflow=high,the viewport consists of that single point.
• Iflow.longitude>high.longitude,the longitude range is inverted (the viewport crosses the 180 degree longitude line).
• Iflow.longitude= -180 degrees andhigh.longitude= 180 degrees, the viewport includes all longitudes.
• Iflow.longitude= 180 degrees andhigh.longitude= -180 degrees, the longitude range is empty.

Bothlowandhighmust be populated, and the represented box cannot be empty. An empty viewport results in an error.

For example, this viewport fully encloses New York City:

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

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

origin

The origin point from which to calculate straight-line distance to the destination (returned asdistanceMeters). If this value is omitted, straight-line distance won't be returned. Must be specified as latitude and longitude coordinates:

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

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];

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

regionCode

The region code used to format the response, specified as accTLD ( "top-level domain" ) two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland" ).

If you specify an invalid region code, the API returns anINVALID_ARGUMENT error. The parameter can affect results based on applicable law.

sessionToken

Session tokens are user-generated strings that track Autocomplete (New) calls as "sessions." Autocomplete (New) uses session tokens to group the query and selection phases of a user autocomplete search into a discrete session for billing purposes. For more information, seeSession tokens.

Autocomplete (New) examples

Use locationRestriction and locationBias

Autocomplete (New) uses IP biasing by default to control the search area. With IP biasing, the API uses the IP address of the device to bias the results. You can optionally uselocationRestrictionor locationBias,but not both, to specify an area to search.

Location restriction specifies the area to search. Results outside the specified area are not returned. The following example uses location restriction to limit the request to a circular location restriction with a 5000-meter radius centered on San Francisco:

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

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

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

With location bias, the location serves as a bias, which means results around the specified location can be returned, including results outside the specified area. The next example changes the previous request to use location bias:

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

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

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

Use types

Use the types parameter to restrict results from a request to be of a certain type as listed inTable AandTable B.You can specify an array of up to five values. If omitted, all types are returned.

The following example specifies a query string of "Soccer" and uses the types parameter to restrict results to establishments of type "sporting_goods_store":

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

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

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

Use origin

When you include theoriginparameter in the request, specified as latitude and longitude coordinates, the API includes the straight-line distance from the origin to the destination in the response. The response returns the distance asdistanceMeters.

This example sets the origin to the center of San Francisco:

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

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

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

Attributions

You can use Autocomplete (New) even without a map. If you do show a map, it must be a Google map. When you display suggestions from the Autocomplete (New) service without a map, you must include the Google logo displayed inline with the search field/results. For more information, seeDisplaying the Google logo and attributions.