Upgrade pre 1.12 Android projects

Since version 5.0.0 this plugin is implemented using the Flutter 1.12 Android plugin APIs. Unfortunately this means App developers also need to migrate their Apps to support the new Android infrastructure. You can do so by following theUpgrading pre 1.12 Android projects migration guide. Failing to do so might result in unexpected behaviour.

AndroidX

The geolocator plugin requires the AndroidX version of the Android Support Libraries. This means you need to make sure your Android project supports AndroidX. Detailed instructions can be foundhere.

The TL;DR version is:

1. Add the following to your "gradle.properties" file:

android.useAndroidX=trueandroid.enableJetifier=true

2. Make sure you set thecompileSdkVersion in your "android/app/build.gradle" file to 35:

android {  compileSdkVersion 35  ...}

3. Make sure you replace all theandroid. dependencies to their AndroidX counterparts (a full list can be found here:Migrating to AndroidX).

Permissions

On Android you'll need to add either theACCESS_COARSE_LOCATION or theACCESS_FINE_LOCATION permission to your Android Manifest. To do so open the AndroidManifest.xml file (located under android/app/src/main) and add one of the following two lines as direct children of the<manifest> tag (when you configure both permissions theACCESS_FINE_LOCATION will be used by the geolocator plugin):

<uses-permissionandroid:name="android.permission.ACCESS_FINE_LOCATION" /><uses-permissionandroid:name="android.permission.ACCESS_COARSE_LOCATION" />

Starting from Android 10 you need to add theACCESS_BACKGROUND_LOCATION permission (next to theACCESS_COARSE_LOCATION or theACCESS_FINE_LOCATION permission) if you want to continue receiving updates even when your App is running in the background:

<uses-permissionandroid:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Starting from Android 14 (SDK 34) you need to add theFOREGROUND_SERVICE_LOCATION permission (next to theACCESS_COARSE_LOCATION or theACCESS_FINE_LOCATION or theACCESS_BACKGROUND_LOCATION permission) if you want to continue receiving updates even when your App is running in the foreground:FOREGROUND_SERVICE_LOCATION

<uses-permissionandroid:name="android.permission.FOREGROUND_SERVICE_LOCATION"

NOTE: Specifying theACCESS_COARSE_LOCATION permission results in location updates with an accuracy approximately equivalent to a city block. It might take a long time (minutes) before you will get your first locations fix asACCESS_COARSE_LOCATION will only use the network services to calculate the position of the device. More information can be foundhere.

On iOS you'll need to add the following entry to your Info.plist file (located under ios/Runner) in order to access the device's location. Simply open your Info.plist file and add the following (make sure you update the description so it is meaningful in the context of your App):

<key>NSLocationWhenInUseUsageDescription</key><string>This app needs access to location when open.</string>

If you don't need to receive updates when your app is in the background, then add a compiler flag as follows: in XCode, click on Pods, choose the Target 'geolocator_apple', choose Build Settings, in the search box look for 'Preprocessor Macros' then add theBYPASS_PERMISSION_LOCATION_ALWAYS=1 flag.Setting this flag prevents your app from requiring theNSLocationAlwaysAndWhenInUseUsageDescription entry in Info.plist, and avoids questions from Apple when submitting your app.

You can also have the flag set automatically by adding the following to theios/Podfile of your application:

post_install do |installer|  installer.pods_project.targets.each do |target|    if target.name == "geolocator_apple"      target.build_configurations.each do |config|        config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)', 'BYPASS_PERMISSION_LOCATION_ALWAYS=1']      end    end  endend

If you do want to receive updates when your App is in the background (or if you don't bypass the permission request as described above) then you'll need to:

• Add the Background Modes capability to your XCode project (Project > Signing and Capabilities > "+ Capability" button) and select Location Updates. Be careful with this, you will need to explain in detail to Apple why your App needs this when submitting your App to the AppStore. If Apple isn't satisfied with the explanation your App will be rejected.
• Add anNSLocationAlwaysAndWhenInUseUsageDescription entry to your Info.plist (useNSLocationAlwaysUsageDescription if you're targeting iOS <11.0)

When using therequestTemporaryFullAccuracy({purposeKey: "YourPurposeKey"}) method, a dictionary should be added to the Info.plist file.

<key>NSLocationTemporaryUsageDescriptionDictionary</key><dict>  <key>YourPurposeKey</key>  <string>The example App requires temporary access to the device&apos;s precise location.</string></dict>

The second key (in this example calledYourPurposeKey) should match the purposeKey that is passed in therequestTemporaryFullAccuracy() method. It is possible to define multiple keys for different features in your app. More information can be found in Apple'sdocumentation.

NOTE: the first time requesting temporary full accuracy access it might take several seconds for the pop-up to show. This is due to the fact that iOS is determining the exact user location which may take several seconds. Unfortunately this is out of our hands.

On macOS you'll need to add the following entries to your Info.plist file (located under macOS/Runner) in order to access the device's location. Simply open your Info.plist file and add the following (make sure you update the description so it is meaningfull in the context of your App):

<key>NSLocationUsageDescription</key><string>This app needs access to location.</string>

You will also have to add the following entry to the DebugProfile.entitlements and Release.entitlements files. This will declare that your App wants to make use of the device's location services and adds it to the list in the "System Preferences" -> "Security & Privace" -> "Privacy" settings.

<key>com.apple.security.personal-information.location</key><true/>

When using therequestTemporaryFullAccuracy({purposeKey: "YourPurposeKey"}) method, a dictionary should be added to the Info.plist file.

<key>NSLocationTemporaryUsageDescriptionDictionary</key><dict>  <key>YourPurposeKey</key>  <string>The example App requires temporary access to the device&apos;s precise location.</string></dict>

The second key (in this example calledYourPurposeKey) should match the purposeKey that is passed in therequestTemporaryFullAccuracy() method. It is possible to define multiple keys for different features in your app. More information can be found in Apple'sdocumentation.

NOTE: the first time requesting temporary full accuracy access it might take several seconds for the pop-up to show. This is due to the fact that macOS is determining the exact user location which may take several seconds. Unfortunately this is out of our hands.

To use the Geolocator plugin on the web you need to be using Flutter 1.20 or higher. Flutter will automatically add the endorsedgeolocator_web package to your application when you add thegeolocator: ^6.2.0 dependency to yourpubspec.yaml.

The following methods of the geolocator API are not supported on the web and will result in aUnsupportedError:

• getLastKnownPosition({ bool forceAndroidLocationManager = true })
• openAppSettings()
• openLocationSettings()
• getServiceStatusStream()

NOTE

Geolocator Web is available only insecure_contexts (HTTPS). More info about the Geolocator API can be foundhere.

To use the Geolocator plugin on Windows you need to be using Flutter 2.10 or higher. Flutter will automatically add the endorsedgeolocator_windows package to your application when you add thegeolocator: ^8.1.0 dependency to yourpubspec.yaml.