Current Place

Using the Places SDK for Android, you can discover the place at the device's currently-reported location. Examples of places include local businesses, points of interest, and geographic locations.

Permissions

To use the library you do not need to declare any additional permissions in your app's manifest, as the library declares all permissions it uses in its manifest. However, if your app uses PlacesClient.findCurrentPlace(), you must request location permissions at runtime.

If your app does not use PlacesClient.findCurrentPlace(), explicitly remove the ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions introduced by the library by adding the following to your manifest:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>
    ...
</manifest>

Read more about permissions and consider using EasyPermissions to get started.

Get the current location

To find the local business or other place where the device is currently located, follow these steps:

1. Call ContextCompat.checkSelfPermission to check whether the user has granted permission to access their device location. Your app must also include code to prompt the user for permission, and to handle the result. See Request App Permissions for details.
2. Create a FindCurrentPlaceRequest, passing a List of Place.Fields, specifying the place data types your app should request.
3. Call PlacesClient.findCurrentPlace(), passing the FindCurrentPlaceRequest you created in the previous step.
4. Get the list of PlaceLikelihoods from the FindCurrentPlaceResponse.

Fields correspond to Place Search results, and are divided into three billing categories: Basic, Contact, and Atmosphere. Basic fields are billed at base rate, and incur no additional charges. Contact and Atmosphere fields are billed at a higher rate. For more information about how Place data requests are billed, see Usage and Billing.

The API returns a FindCurrentPlaceResponse in a Task. The FindCurrentPlaceResponse contains a list of PlaceLikelihood objects representing places where the device is likely to be located. For each place, the result includes an indication of the likelihood that the place is the right one. The list may be empty, if there is no known place corresponding to the given device location.

You can call PlaceLikelihood.getPlace() to retrieve a Place object, and PlaceLikelihood.getLikelihood() to get the place's likelihood rating. A higher value means a greater probability that the place is the best match.

The following code sample retrieves the list of places where the device is most likely to be located, and logs the name and likelihood for each place.

// Use fields to define the data types to return.
val placeFields: List<Place.Field> = listOf(Place.Field.NAME)

// Use the builder to create a FindCurrentPlaceRequest.
val request: FindCurrentPlaceRequest = FindCurrentPlaceRequest.newInstance(placeFields)

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED) {

    val placeResponse = placesClient.findCurrentPlace(request)
    placeResponse.addOnCompleteListener { task ->
        if (task.isSuccessful) {
            val response = task.result
            for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) {
                Log.i(
                    TAG,
                    "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}"
                )
            }
        } else {
            val exception = task.exception
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }
    }
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission()
}

      

// Use fields to define the data types to return.
List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME);

// Use the builder to create a FindCurrentPlaceRequest.
FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields);

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request);
    placeResponse.addOnCompleteListener(task -> {
        if (task.isSuccessful()){
            FindCurrentPlaceResponse response = task.getResult();
            for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) {
                Log.i(TAG, String.format("Place '%s' has likelihood: %f",
                    placeLikelihood.getPlace().getName(),
                    placeLikelihood.getLikelihood()));
            }
        } else {
            Exception exception = task.getException();
            if (exception instanceof ApiException) {
                ApiException apiException = (ApiException) exception;
                Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            }
        }
    });
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission();
}

      

Notes about the likelihood values:

• The likelihood provides a relative probability of the place being the best match within the list of returned places for a single request. You can't compare likelihoods across different requests.
• The value of the likelihood will be between 0.0 and 1.0.

For example, to represent a 55% likelihood that the correct place is Place A, and a 35% likelihood that it's Place B, the response has two members, Place A with a likelihood of 0.55 and Place B with a likelihood of 0.35.

Display attributions in your app

When your app displays information obtained from PlacesClient.findCurrentPlace(), the app must also display attributions. See the documentation on attributions.