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:
- Call
ContextCompat.checkSelfPermissionto 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. - Create a
FindCurrentPlaceRequest, passing aListofPlace.Fields, specifying the place data types your app should request. - Call
PlacesClient.findCurrentPlace(), passing theFindCurrentPlaceRequestyou created in the previous step. - Get the list of
PlaceLikelihoods from theFindCurrentPlaceResponse.
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.
Kotlin
// 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 () }
Java
// 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
.
