Place Autocomplete

The autocomplete service in the Place Kit returns place predictions in response to user search queries. As the user types, the autocomplete service returns suggestions for places such as businesses, addresses, and points of interest.

Get place predictions programmatically

You can create a custom search UI as an alternative to the UI provided by the autocomplete widget. To do this, your app must get place predictions programmatically. Your app can get a list of predicted place names and/or addresses from the autocomplete API by calling PlacesClient.findAutocompletePredictions(), passing a FindAutocompletePredictionsRequest object with the following parameters:

• Required: A query string containing the text typed by the user.

• Optional: One two-letter country code (ISO 3166-1 Alpha-2), indicating the country to which results should be restricted.

• Optional: A TypeFilter, which you can use to restrict the results to the specified place type. The following place types are supported:

  • TypeFilter.GEOCODE – Returns only geocoding results, rather than businesses. Use this request to disambiguate results where the specified location may be indeterminate.

  • TypeFilter.ADDRESS – Returns only autocomplete results with a precise address. Use this type when you know the user is looking for a fully specified address.

  • TypeFilter.ESTABLISHMENT – Returns only places that are businesses.

  • TypeFilter.REGIONS – Returns only places that match one of the following types:

    • LOCALITY
    • SUBLOCALITY
    • POSTAL_CODE
    • COUNTRY
    • ADMINISTRATIVE_AREA_LEVEL_1
    • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES – Returns only results matching LOCALITY or ADMINISTRATIVE_AREA_LEVEL_3.

For information about place types, see the guide to place types.

The example below shows a complete call to PlacesClient.findAutocompletePredictions().

mPlacesClient.findAutocompletePredictions(newRequest)
        .addOnSuccessListener(new OnSuccessListener<FindAutocompletePredictionsResponse>() {
            @Override
            public void onSuccess(@Nullable FindAutocompletePredictionsResponse response) {
                for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
                    Log.i(TAG, prediction.getPlaceId());
                    Log.i(TAG, prediction.getPrimaryText());
                }
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception exception) {
                Log.e(TAG, Log.getStackTraceString(exception));
            }
        });

The API returns an FindAutocompletePredictionsResponse in a Task. The FindAutocompletePredictionsResponse contains a list of AutocompletePrediction objects representing predicted places. The list may be empty, if there is no known place corresponding to the query and the filter criteria.

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

• getPrimaryText() returns the main text describing a place. This is usually the name of the place. Examples: "Eiffel Tower", and "123 Pitt Street".

• getSecondaryText() returns the subsidiary text of a place description. This is useful, for example, 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 textual identifier that uniquely identifies a place, which you can use to retrieve the Place object again later.

Usage limits

Please consults with the API provider's documentation on usage limits.

Display attributions in your app

Please consults with the API provider's documentation on attributions.

Troubleshooting

Please consults with the API provider's documentation on troubleshooting.