Developer Console
Sign In
Sign In
Developer Console

Common A3L Location APIs

This page describes common A3L Location APIs you can use in your app to support the primary functions of A3L Location described in Integrate A3L Location SDK.

Check settings

To get the current state of the location settings, call the A3LLocationSettingsResponse.getLocationSettingsStates() method.

To make sure the system settings of a user's device are in a state that allow location services to successfully perform location requests, use the checkLocationSettings() API. If the API determines that the required settings aren't enabled on the device, you can choose to display a dialog to the user that guides them to enable the setting.

Before you can check the system settings, you must create an A3LLocationSettingsRequest.Builder object that includes the A3LLocationRequest objects that your app uses. The following code shows an example of creating an A3LLocationSettingsRequest.Builder object with two location requests.

A3LLocationSettingsRequest.Builder builder = new A3LLocationSettingsRequest.Builder()
        .addLocationRequest(mLocationRequestHighAccuracy)
        .addLocationRequest(mLocationRequestBalancedPowerAccuracy);

If your app uses Bluetooth Low Energy (BLE) for location, build your A3LLocationSettingsRequest.Builder object using the setNeedBle() method, as shown in the following code.

builder.setNeedBle(true);

To check the system settings in your app, build the A3LLocationSettingsRequest object and pass it to the checkLocationSettings() method of the A3LSettingsClient class, as shown in the following example.

Task<A3LLocationSettingsResponse> result =
        A3LLocationServices.getSettingsClient(this).checkLocationSettings(builder.build());

Add an on complete listener to the Task to handle the result. If the result throws an exception, your app can conditionally check the status codes to determine if the issue can be resolved. If the status code is RESOLUTION_REQUIRED, you can show a dialog to the user to ask them to allow the required setting. To do this, call ResolvableApiException.startResolutionForResult(), as shown in the following example.

result.addOnCompleteListener(new OnCompleteListener<A3LLocationSettingsResponse>() {
    @Override
    public void onComplete(Task<A3LLocationSettingsResponse> task) {
        try {
            A3LLocationSettingsResponse response = task.getResult(ApiException.class);
            // System settings can allow location services.
            ...
        } catch (ApiException exception) {
            switch (exception.getStatusCode()) {
                case A3LLocationSettingsStatusCodes.RESOLUTION_REQUIRED:
                    // System settings are not in a state to allow location services, but
                    // can be resolved.
                    try {
                        // Cast to a resolvable exception.
                        ResolvableApiException resolvable = (ResolvableApiException) exception;
                        // Show a dialog to the user to resolve - verify results in onActivityResult().
                        resolvable.startResolutionForResult(
                                OuterClass.this,
                                REQUEST_CHECK_SETTINGS);
                    } catch (SendIntentException e) {
                        // Ignore
                    } catch (ClassCastException e) {
                        // Ignore
                    }
                    break;
                case A3LLocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
                    // System settings are not in a state to allow location services and
                    // can't be resolved.
                    ...
                    break;
            }
        }
    }
});

For more information on status codes, see the API documentation for A3LLocationSettingsStatusCodes.

The following example shows how to verify the results of startResolutionForResult() in the onActivityResult() method.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    switch (requestCode) {
        case REQUEST_CHECK_SETTINGS:
            switch (resultCode) {
                case Activity.RESULT_OK:
                    // User changed required settings
                   ...
                    break;
                case Activity.RESULT_CANCELED:
                    // User did not change required settings
                    ...
                    break;
                default:
                    break;
            }
            break;
    }
}

Get location availability

To determine if location data is available, use the getLocationAvailability() method. A successful Task result returns an A3LLocationAvailability object. To get a Boolean that indicates the likelihood that location data can be retrieved, use the isLocationAvailable() method. A true response doesn't guarantee the location is available, but it indicates the location data is likely to be available. Similarly, a false response doesn't confirm the location is unavailable, but it indicates the location data is likely to be unavailable. The following code shows an example of how to get location availability.

// getLocationAvailability
Task<A3LLocationAvailability> a3LLocationAvailability = a3LLocationProviderClient.getLocationAvailability();
a3LLocationAvailability.addOnCompleteListener(new OnCompleteListener<A3LLocationAvailability>() {
    @Override
    public void onComplete(@NonNull Task<A3LLocationAvailability> task) {
        // Code to execute on completion 
        // ...
        if(task.isSuccessful()) {
            // Use isLocationAvailable() to check if location APIs can retrieve a location.
            // The result does not guarantee that the APIs can fetch a location, but it's likely to get one.
            Boolean locationAvailable = task.getResult().isLocationAvailable();
        }
    }
});

For Android devices without Google Play services, the getLocationAvailability() method only verifies whether the location is enabled or disabled.

Request continuous location updates

The requestLocationUpdates() method allows your app to repeatedly get location updates. If your app tracks users' locations over time, this API can handle that use case. The requestLocationUpdates() method takes an A3LLocationRequest, an A3LLocationListener and a Looper. The API delivers results to the listener on the looper provided. If your app makes a location update request and your app previously made a location update request using the same listener, the new request replaces the previous one. The following code shows an example of how to request location updates.

// Request location updates
A3LLocationListener a3lLocationListener = new A3LLocationListener() {
    @Override
    public void onLocationChanged(@NonNull Location location) {
        // Custom code to be executed once location is received.

    }
};
// The value of 1000L is an example. Use any value for A3LLocationRequest intervalMillis or use 
// other builder constructors. For other options, see the Javadoc API reference.
A3LLocationRequest a3lLocationRequest = new A3LLocationRequest.Builder(1000L).build();
// A different looper can be provided. If looper is null, it uses the looper associated with the calling thread.
Task<Void> locationUpdates = a3LLocationProviderClient.requestLocationUpdates(a3lLocationRequest, a3lLocationListener, null);

Stop location updates

To stop location updates on a listener, use the removeLocationUpdates() method, as shown in the following code. The removeLocationUpdates() takes an A3lLocationListener object.

// Remove location updates
Task<Void> removeLocationUpdatesTask = a3LLocationProviderClient.removeLocationUpdates(a3lLocationListener);

Last updated: Sep 13, 2023