AI-generated Key Takeaways

outlined_flag

• Autocomplete (New) provides on-the-fly place predictions based on user input, using text search and geographic bounds for refined results.

• Developers can use parameters liketypesFilter,locationBias, andlocationRestriction to customize the search area and types of places returned.

• Responses include up to five predictions, each with details like the full place description, place ID, and distance from a specified origin.

• It's available in Places SDK for Android version 3.5.0 and later, and session tokens are recommended for billing purposes in programmatic sessions.

• Location restriction limits results to a defined area, while location bias prioritizes results within an area but allows others, and primary types filter by place categories.

Autocomplete (New) returns place predictions inresponse to a request that includes a text search string and geographic boundsthat control the search area. Autocomplete can matchon full words and substrings of the input, resolving place names, addresses, andplus codes. Your application can send queriesas the user types, to provide on-the-fly place and query predictions.

For example, you call Autocomplete using as input astring that contains a partial user input, "Sicilian piz", with the search arealimited to San Francisco, CA. The response then contains a list of placepredictions that match the search string and search area, such as the restaurantnamed "Sicilian Pizza Kitchen". The returned place predictions are designed tobe presented to the user to aid them in selecting the desired place. You canmake aPlace Details(New) request to get moreinformation about any of the returned place predictions.

You can integrate Autocomplete (New) functionality into your app in two mainways:

• Add the Place Autocomplete widget: Provides aready-to-use search autocomplete experience through thePlaceAutocompleteclass that displays predictions as the user types.
• Get place predictions programmatically: Call theAPI directly to retrieve predictions and display them in a custom userinterface.

Add the Place Autocomplete widget

To more easily provide a consistent place autocomplete experience, you can addthe Place Autocomplete widget to your app. The widget provides a dedicated,full-screen interface that handles user input and displays place predictions tothe user while returningAutocompletePredictionobjects to the app. You can then make aPlace Details(New) request to getadditional information about any of the place predictions.

Like whengetting place predictions programmatically,the Place Autocomplete widget lets you usesession tokens togroup autocomplete requests into session for billing purposes. You can pass asession token when creating the intent for the widget by callingsetAutocompleteSessionToken(). If you don't provide a session token, thewidget will create one for you, which you can access by callinggetSessionTokenFromIntent(). For more information on using session tokens, seeAbout sessiontokens.

To add the Place Autocomplete widget to your app:

1. (Optional) Define a session token. If you don't provide a session token, thewidget will create one for you.

2. Define anautocompleteIntent with the desired parameters and your sessiontoken.

3. Define anActivityResultLauncher forStartActivityForResult. Thislauncher will handle the result returned from the autocomplete activity.

4. Handle the result in theActivityResultLauncher's callback. This involvesextracting theAutocompletePrediction andAutocompleteSessionToken (ifyou haven't provided your own), handling errors, and optionally making afetchPlace() request to get additional details about a place.

5. Launch the intent using theplaceAutocompleteActivityResultLauncher

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.Places.initializeWithNewPlacesApiEnabled(/* Context= */context,/* API Key= */key)// Optional, create a session token for Autocomplete request and the followup FetchPlace request.valsessionToken:AutocompleteSessionToken=AutocompleteSessionToken.newInstance()valautocompleteIntent:Intent=PlaceAutocomplete.createIntent(this){// ... provide input params for origin, countries, types filter ...setAutocompleteSessionToken(sessionToken)}valplaceAutocompleteActivityResultLauncher:ActivityResultLauncher<Intent>=registerForActivityResult(ActivityResultContracts.StartActivityForResult()){result:ActivityResult->valintent=result.dataif(intent!=null &&result.resultCode==PlaceAutocompleteActivity.RESULT_OK){// get prediction objectvalprediction:AutocompletePrediction?=PlaceAutocomplete.getPredictionFromIntent(intent!!)// get session tokenvalsessionToken:AutocompleteSessionToken?=PlaceAutocomplete.getSessionTokenFromIntent(intent!!)// create PlacesClient to make FetchPlace request (optional)valplacesClient:PlacesClient=Places.createClient(this)valresponse=placesClient.awaitFetchPlace(prediction.placeId,Field.DISPLAY_NAME){sessionToken=sessionToken// optional}}}// Launch ActivityplaceAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.Places.initializeWithNewPlacesApiEnabled(/* Context= */context,/* API Key= */key);// Optional, create a session token for Autocomplete request and the followup FetchPlace requestAutocompleteSessionTokensessionToken=AutocompleteSessionToken.newInstance();IntentautocompleteIntent=newPlaceAutocomplete.IntentBuilder()// ... set input params for origin, countries, types filter ....setSessionToken(sessionToken)// optional.build(this);ActivityResultLauncher<Intent>placeAutocompleteActivityResultLauncher=registerForActivityResult(newActivityResultContracts.StartActivityForResult(),newActivityResultCallback<ActivityResult>(){@OverridepublicvoidonActivityResult(ActivityResultresult){Intentintent=result.getData();if(result.getResultCode()==PlaceAutocompleteActivity.RESULT_OK){// get prediction objectAutocompletePredictionprediction=PlaceAutocomplete.getPredictionFromIntent(Preconditions.checkNotNull(intent));// get session tokenAutocompleteSessionTokensessionToken=PlaceAutocomplete.getSessionTokenFromIntent(Preconditions.checkNotNull(intent));// create PlacesClient to make FetchPlace request (optional)PlacesClientplacesClient=Places.createClient(this);FetchPlaceRequestrequest=FetchPlaceRequest.builder(prediction.getPlaceId(),Arrays.asList(Field.DISPLAY_NAME)).setSessionToken(sessionToken).build();Task<FetchPlaceResponse>task=placesClient.fetchPlace(request);}}});// Launch ActivityplaceAutocompleteActivityResultLauncher.launch(autocompleteIntent);

<?xmlversion="1.0"encoding="utf-8"?><resources><stylename="BrandedTheme"parent="PlacesMaterialTheme"><!-- Color tokens. --><itemname="placesColorOnNeutralContainer">#5300e8</item><itemname="placesColorOnNeutralContainerVariant">#ee6002</item>...<!-- Typography tokens. --><itemname="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item><itemname="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>...<!-- Spacing tokens. --><itemname="placesSpacingSmall">6dp</item><itemname="placesSpacingMedium">12dp</item>...<!-- Attribution tokens. --><itemname="placesColorAttributionLightTheme">white</item><itemname="placesColorAttributionDarkTheme">black</item></style></resources>

You can then reference the override styles by callingsetAutocompleteUiCustomization:

ActivityResultLauncher<Intent>placeAutocompleteActivityResultLauncher=registerForActivityResult(newActivityResultContracts.StartActivityForResult(),newActivityResultCallback<ActivityResult>(){@OverridepublicvoidonActivityResult(ActivityResultresult){Intentintent=result.getData();if(intent!=null){AutocompletePredictionprediction=PlaceAutocomplete.getPredictionFromIntent(intent);AutocompleteSessionTokensessionToken=PlaceAutocomplete.getSessionTokenFromIntent(intent);Statusstatus=PlaceAutocomplete.getResultStatusFromIntent(intent);...}}});IntentplaceAutocompleteIntent=newPlaceAutocomplete.IntentBuilder().setInitialQuery("INSERT_QUERY_TEXT").setOrigin(newLatLng(10.0,10.0))....setAutocompleteUiCustomization(AutocompleteUiCustomization.builder().listItemIcon(AutocompleteUiIcon.noIcon()).listDensity(AutocompleteListDensity.MULTI_LINE).theme(R.style.BrandedTheme).build()).build(this);placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Get place predictions programmatically

Your app can get a list of predicted place names and/or addresses from theautocomplete API by callingPlacesClient.findAutocompletePredictions(),passing aFindAutocompletePredictionsRequestobject. The example below shows a complete call toPlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);final List<Field> placeFields = getPlaceFields();LatLng center = new LatLng(37.7749, -122.4194);CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);final FindAutocompletePredictionsRequest autocompletePlacesRequest =    FindAutocompletePredictionsRequest.builder()            .setQuery("Sicilian piz")            .setRegionCode("ES")            .setLocationRestriction(circle)            .build());placesClient.findAutocompletePredictions(autoCompletePlacesRequest)    .addOnSuccessListener(        (response) -> {            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();          }    ).addOnFailureListener(        exception -> {            Log.e(TAG, "some exception happened" + exception.getMessage());        })    );

You can use aCancellationTokento attempt to cancel a request to any of the request classes (for example,FetchPlaceRequest). Cancellation is done on a best-effort basis.Once a cancellation request is issued, no response will be returned.Issuing a cancellation token does NOT guarantee that a particular requestwill be cancelled, and you may still be charged for the request even if noresponse is returned.

Autocomplete (New) responses

The API returns anFindAutocompletePredictionsResponsein aTask.TheFindAutocompletePredictionsResponsecontains a list of up to fiveAutocompletePredictionobjects representing predicted places. The list may be empty, if there is noknown place corresponding to the query and the filter criteria.

For each predicted place, you can call the following methods to retrieve placedetails:

• getFullText(CharacterStyle)returns the full text of a place description. This is a combination of theprimary and secondary text. Example: "Eiffel Tower, Avenue Anatole France,Paris, France". In addition, this method lets you highlight the sections of thedescription that match the search with a style of your choice, usingCharacterStyle.TheCharacterStyle parameter is optional. Set it to null if you don't needany highlighting.
• getPrimaryText(CharacterStyle)returns the main text describing a place. This is usually the name of theplace. Examples: "Eiffel Tower", and "123 Pitt Street".
• getSecondaryText(CharacterStyle)returns the subsidiary text of a place description. This is useful, forexample, as a second line when showing autocomplete predictions. Examples:"Avenue Anatole France, Paris, France", and "Sydney, New South Wales".
• getPlaceId()returns the place ID of the predicted place. A place ID is a textualidentifier that uniquely identifies a place, which you can use to retrievethePlaceobject again later. For more information about place IDs inAutocomplete, seePlace Details(New). For generalinformation about place IDs, see thePlace IDoverview.
• getTypes()returns the list of place types associated with this place.
• getDistanceMeters()returns the straight-line distance in meters between this place and theorigin specified in the request.

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.

  To set the query parameter, call thesetQuery() method when building theFindAutocompletePredictionsRequest object.

Optional parameters

• Primary types

  A list of up to five type type values from typesTable A orTable B used to filter the places returned in the response. A place must match one of the specified primary type values to be included in the response.

  A place can only have a single primary type from typesTable A orTable B associated with it. For example, the primary type might be"mexican_restaurant" or"steak_house".

  The request is rejected with anINVALID_REQUEST error if:

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

  To set the primary types parameter, call thesetTypesFilter() method when building theFindAutocompletePredictionsRequest object.

• Countries

  Only include results from the list of specified countries, specified as a list 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:

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

  To set the countries parameter, call thesetCountries() method when building theFindAutocompletePredictionsRequest object.

• Input offset

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

  To set the input offset parameter, call thesetInputOffset() method when building theFindAutocompletePredictionsRequest object.

• Location bias or location restriction

  You can specify a location bias or location restriction, but not both, to define the search area. Think of location restriction as specifying the region which the results must be within, and location bias as specifying the region that the results must be near. The key difference is that with location bias, results outside of the specified region may still be returned.

  • Location bias

    Specifies an area to search. This location serves as a bias, not a restriction, so results outside the specified area may still be returned.

    To set the location bias parameter, call thesetLocationBias() method when building theFindAutocompletePredictionsRequest object.

  • Location restriction

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

    To set the location restriction parameter, call thesetLocationRestriction() method when building theFindAutocompletePredictionsRequest object.

  Specify the location bias or location restriction region 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 location restriction, you must set the radius to a value greater than 0.0. Otherwise, the request returns no results.

  • A rectangle is a latitude-longitude viewport, represented as two diagonally oppositelow andhigh points. 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:

    Note: The supported bias types vary depending on the SDK version that you are using.CircularBounds is only available in Autocomplete (New).
    • 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.

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

• Origin

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

  To set the origin parameter, call thesetOrigin() method when building theFindAutocompletePredictionsRequest object.

• Region code

  The region code used to format the response, including address formatting, 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").

  Note: The region code is intended to represent the region that the request is originating from, not necessarily the target region for the query.

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

  To set the region code parameter, call thesetRegionCode() method when building theFindAutocompletePredictionsRequest object.

• Session token

  Session tokens are user-generated strings that track Autocomplete (New) calls—both calls made through the widget and programmatic calls—as "sessions." Autocomplete uses session tokens to group the query and selection phases of a user autocomplete search into a discrete session for billing purposes. The session begins when the user starts typing a query, and concludes when they select a place. Each session can have multiple queries, followed by one place selection. Once a session has concluded, the token is no longer valid; your app must generate a fresh token for each session. We recommend using session tokens for all programmatic autocomplete sessions (when you embed a fragment, or launch autocomplete using an intent, the API takes care of this automatically).

  The Autocomplete uses aAutocompleteSessionToken to identify each session. Your app should pass a new session token upon beginning each new session, then pass that same token, along with a Place ID, in the subsequent call tofetchPlace() to retrieve Place Details for the place that was selected by the user.

  To set the session token parameter, call thesetSessionToken() method when building theFindAutocompletePredictionsRequest object.

  For more information, seeSession tokens.

Autocomplete (New) examples

Use location restriction and location bias

Autocomplete (New) uses IP biasing by default tocontrol the search area. With IP biasing, the API uses the IP address of thedevice to bias the results. You can optionally uselocationrestriction orlocation bias, but notboth, to specify an area to search.

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);final List<Field> placeFields = getPlaceFields();LatLng center = new LatLng(37.7749, -122.4194);CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);final FindAutocompletePredictionsRequest autocompletePlacesRequest =    FindAutocompletePredictionsRequest.builder()            .setQuery("Amoeba")            .setLocationRestriction(circle)            .build());placesClient.findAutocompletePredictions(autoCompletePlacesRequest)    .addOnSuccessListener(        (response) -> {            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();          }    ).addOnFailureListener(        exception -> {            Log.e(TAG, "some exception happened" + exception.getMessage());        })    );

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);final List<Field> placeFields = getPlaceFields();LatLng center = new LatLng(37.7749, -122.4194);CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);final FindAutocompletePredictionsRequest autocompletePlacesRequest =    FindAutocompletePredictionsRequest.builder()            .setQuery("Amoeba")            .setLocationBias(circle)            .build());placesClient.findAutocompletePredictions(autoCompletePlacesRequest)    .addOnSuccessListener(        (response) -> {            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();          }    ).addOnFailureListener(        exception -> {            Log.e(TAG, "some exception happened" + exception.getMessage());        })    );

Use primary types

Use theprimary types parameter to restrict results from arequest to be of a certain type as listed inTableA andTableB. You can specifyan array of up to five values. If omitted, all types are returned.

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);final List<Field> placeFields = getPlaceFields();final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");LatLng center = new LatLng(37.7749, -122.4194);CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);final FindAutocompletePredictionsRequest autocompletePlacesRequest =    FindAutocompletePredictionsRequest.builder()            .setQuery("Soccer")            .setIncludedPrimaryTypes(primaryTypes)            .setLocationBias(circle)            .build());placesClient.findAutocompletePredictions(autoCompletePlacesRequest)    .addOnSuccessListener(        (response) -> {            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();          }    ).addOnFailureListener(        exception -> {            Log.e(TAG, "some exception happened" + exception.getMessage());        })    );

If you omit the primary types parameter, the results can include establishmentsof a type that you may not want, such as"athletic_field".

Use origin

When you include theorigin parameter in the request, specified aslatitude and longitude coordinates, the API includes the straight-line distancefrom the origin to the destination in the response (accessed usinggetDistanceMeters()).This example sets the origin to the center of San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);final List<Field> placeFields = getPlaceFields();LatLng center = new LatLng(37.7749, -122.4194);CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);final FindAutocompletePredictionsRequest autocompletePlacesRequest =    FindAutocompletePredictionsRequest.builder()            .setQuery("Amoeba")            .setOrigin(center)            .setLocationRestriction(circle)            .build());placesClient.findAutocompletePredictions(autoCompletePlacesRequest)    .addOnSuccessListener(        (response) -> {            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();          }    ).addOnFailureListener(        exception -> {            Log.e(TAG, "some exception happened" + exception.getMessage());        })    );