Request location permissions

To protect user privacy, apps that use location services must request location permissions.

When you request location permissions, follow the same best practices as you would for any other runtime permission. One important difference when it comes to location permissions is that the system includes multiple permissions related to location. Which permissions you request, and how you request them, depend on the location requirements for your app's use case.

This page describes the different types of location requirements and provides guidance on how to request location permissions in each case.

Types of location access

Android's location permissions deal with the following categories of location access:

This section describes the situations when your app uses each category.

Foreground location

If your app contains a feature that shares or receives location information only once, or for a defined amount of time, then that feature requires foreground location access. Some examples include the following:

  • Within a navigation app, a feature allows users to get turn-by-turn directions.
  • Within a messaging app, a feature allows users to share their current location with another user.

The system considers your app to be using foreground location if a feature of your app accesses the device's current location in one of the following situations:

  • An activity that belongs to your app is visible.
  • Your app is running a foreground service. When a foreground service is running, the system raises user awareness by showing a persistent notification. Your app retains access when it's placed in the background, such as when the user presses the Home button on their device or turns their device's display off.

    Additionally, it's recommended that you declare a foreground service type of location, as shown in the following code snippet. On Android 10 (API level 29) and higher, you must declare this foreground service type.

    <!-- Recommended for Android 9 (API level 28) and lower. -->
    <!-- Required for Android 10 (API level 29) and higher. -->
        android:foregroundServiceType="location" ... >
        <!-- Any inner elements would go here. -->

You declare a need for foreground location when your app requests either the ACCESS_COARSE_LOCATION permission or the ACCESS_FINE_LOCATION permission, as shown in the following snippet:

<manifest ... >
  <!-- To request foreground location access, declare one of these permissions. -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

The level of precision depends on which permission you request:

Provides an estimate of the device's location, to within about 1 mile (1.6 km).
Provides an estimate of the device's location that is as accurate as possible, usually within about 160 feet (50 meters) and sometimes as accurate as within 10 feet (a few meters) or better.

This permission is necessary for some connectivity tasks, such as connecting to nearby devices over Bluetooth Low Energy (BLE).

Background location

An app requires background location access if a feature within the app constantly shares location with other users or uses the Geofencing API. Several examples include the following:

  • Within a family location sharing app, a feature allows users to continuously share location with family members.
  • Within an IoT app, a feature allows users to configure their home devices such that they turn off when the user leaves their home and turn back on when the user returns home.

The system considers your app to be using background location if it accesses the device's current location in any situation other than the ones described in the foreground location section. The background location precision is the same as the foreground location precision, which depends on the location permissions that your app declares.

On Android 10 (API level 29) and higher, you must declare the ACCESS_BACKGROUND_LOCATION permission in your app's manifest in order to request background location access at runtime. On earlier versions of Android, when your app receives foreground location access, it automatically receives background location access as well.

<manifest ... >
  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Request location access at runtime

When a feature in your app needs location access, wait until the user interacts with the feature before making the permission request. This workflow follows the best practice of asking for runtime permissions in context, as described in the guide that explains how to request app permissions.

Figure 1 shows an example of how to perform this process. The app contains a "share location" feature that requires foreground location access. The app doesn't request the location permission, however, until the user selects the Share location button.

After the user selects the Share Location button, the
    system's location permission dialog appears
Figure 1. Location-sharing feature that requires foreground location access. The feature is enabled if the user selects Allow only while using the app.

Even if several features in your app require location access, it's likely that only some of them require background location access. Therefore, it's recommended that your app performs incremental requests for location permissions, asking for foreground location access and then background location access. By performing incremental requests, you give users more control and transparency because they can better understand which features in your app need background location access.

Figure 2 shows an example of an app that's designed to handle incremental requests. Both the "show current location" and "recommend nearby places" features require foreground location access. Only the "recommend nearby places" feature, however, requires background location access.

The button that enables foreground location access is
    positioned half a screen length away from the button that enables background
Figure 2. Both features require location access, but only the "recommend nearby features" feature requires background location access.

The process for performing incremental requests is as follows:

  1. At first, your app should guide users to the features that require foreground location access, such as the "share location" feature in Figure 1 or the "show current location" feature in Figure 2.

    It's recommended that you disable user access to features that require background location access until your app has foreground location access.

  2. At a later time, when the user explores functionality that requires background location access, you can request background location access.

Request background location

Figure 3. Settings page includes an option called Allow all the time, which grants background location access.

When a feature in your app requests background location on a device that runs Android 10 (API level 29), the system permissions dialog includes an option named Allow all the time. If the user selects this option, the feature in your app gains background location access.

On Android 11 (API level 30) and higher, however, the system dialog doesn't include the Allow all the time option. Instead, users must enable background location on a settings page, as shown in figure 3.

You can help users navigate to this settings page by following best practices when requesting the background location permission. The process for granting the permission depends on your app's target SDK version.

App targets Android 11 or higher

If your app hasn't been granted the ACCESS_BACKGROUND_LOCATION permission, and shouldShowRequestPermissionRationale() returns true, show an educational UI to users that includes the following:

  • A clear explanation of why your app's feature needs access to background location.
  • The user-visible label of the settings option that grants background location (for example, Allow all the time in figure 3). You can call getBackgroundPermissionOptionLabel() to get this label. The return value of this method is localized to the user's device language preference.
  • An option for users to decline the permission. If users decline background location access, they should be able to continue using your app.
Users can tap the system notification to change location
  settings for an app
Figure 4. Notification reminding the user that they've granted background location access to an app.

App targets Android 10 or lower

When a feature in your app requests background location access, users see a system dialog. This dialog includes an option to navigate to your app's location permission options on a settings page.

As long as your app already follows best practices for requesting location permissions, you don't need to make any changes to support this behavior.

Reminder of background location grant

On Android 10 and higher, when a feature in your app accesses device location in the background for the first time after the user grants background location access, the system schedules a notification to send to the user. This notification reminds the user that they've allowed your app to access device location all the time. An example notification appears in figure 4.

Additional resources

For more information about location permissions in Android, view the following materials: