ym_geolocator_android

Android implementation of the Flutter geolocation platform interface.

ym_geolocator_android provides location permissions, one-time location requests, continuous location updates, service-status updates, Android settings shortcuts, and Android-specific location settings. It is an Android implementation package only; it does not provide iOS, web, Windows, macOS, or Linux support.

Requirements

  • Flutter 3.32.0 or newer
  • Dart 3.8.0 or newer
  • An AndroidX Flutter project
  • Android location permissions declared in the application manifest

The Android module uses the Flutter project's Android SDK configuration. The current development setup builds with Java 17, Android Gradle Plugin 9.0.1, and Gradle 9.1.0.

Installation

Add the package to the Android application that needs location access:

dependencies:
  ym_geolocator_android: ^0.0.3

Then fetch packages:

flutter pub get

If the package is being consumed directly from GitHub instead of pub.dev:

dependencies:
  ym_geolocator_android:
    git:
      url: https://github.com/yashmanghnani/ym_geolocator_android.git

Android manifest setup

Add the location permissions to the app's android/app/src/main/AndroidManifest.xml. The plugin contributes its foreground location service, but the application must declare the permissions it needs:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <application
        android:label="Your App"
        android:name="${applicationName}">
        <!-- Your existing Flutter activity and application configuration. -->
    </application>
</manifest>

Add these permissions when using a foreground notification for continuous updates:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

For Android 10 and newer background-location flows, also declare the following only when the application genuinely needs background location permission:

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

Request permissions at runtime before reading location. Declaring a permission in the manifest alone is not enough.

Basic usage

The plugin registers itself as the Android GeolocatorPlatform implementation. Use the platform interface in application code:

import 'package:geolocator_platform_interface/geolocator_platform_interface.dart';
import 'package:ym_geolocator_android/ym_geolocator_android.dart';

final GeolocatorPlatform geolocator = GeolocatorPlatform.instance;

Future<Position?> readCurrentPosition() async {
  if (!await geolocator.isLocationServiceEnabled()) {
    await geolocator.openLocationSettings();
    return null;
  }

  var permission = await geolocator.checkPermission();

  if (permission == LocationPermission.denied) {
    permission = await geolocator.requestPermission();
  }

  if (permission == LocationPermission.denied ||
      permission == LocationPermission.deniedForever) {
    if (permission == LocationPermission.deniedForever) {
      await geolocator.openAppSettings();
    }
    return null;
  }

  return geolocator.getCurrentPosition(
    locationSettings: AndroidSettings(
      accuracy: LocationAccuracy.high,
      timeLimit: Duration(seconds: 15),
    ),
  );
}

For the standard cross-platform geolocator facade, use that package in the application and let Flutter select the endorsed platform implementation. Use this package directly when the application intentionally depends on the Android implementation.

Continuous location updates

Use getPositionStream for live updates. Always keep the subscription and cancel it when the screen or feature is disposed:

import 'dart:async';

StreamSubscription<Position>? positionSubscription;

void startLocationUpdates() {
  final settings = AndroidSettings(
    accuracy: LocationAccuracy.best,
    distanceFilter: 10,
    intervalDuration: const Duration(seconds: 5),
  );

  positionSubscription = geolocator
      .getPositionStream(locationSettings: settings)
      .listen(
        (position) {
          // Update application state or send the position to your backend.
        },
        onError: (Object error) {
          // Handle permission, service, timeout, or update errors.
        },
      );
}

Future<void> stopLocationUpdates() async {
  await positionSubscription?.cancel();
  positionSubscription = null;
}

There should be one active position stream for an Android implementation instance. Cancel the current subscription before starting a separate location flow.

Android-specific settings

AndroidSettings extends the shared LocationSettings class and supports:

Setting Purpose
accuracy Desired location accuracy and power usage.
distanceFilter Minimum movement in meters before an update is emitted.
intervalDuration Desired interval for active updates. Defaults to 5 seconds when omitted.
timeLimit Timeout for a current-position request or position stream.
forceLocationManager Forces Android's legacy LocationManager instead of the fused provider.
useMSLAltitude Uses MSL altitude from NMEA data for position-stream updates when supported.
foregroundNotificationConfig Starts the plugin's foreground location service with a persistent notification.

The plugin automatically falls back to LocationManager when Google Play Services are unavailable. To force that path explicitly:

final settings = AndroidSettings(
  forceLocationManager: true,
  accuracy: LocationAccuracy.high,
);

If an application excludes Google Play Services from its Android dependency graph, the same fallback can be configured in android/app/build.gradle:

configurations.implementation {
    exclude group: 'com.google.android.gms'
}

Foreground location notification

Pass ForegroundNotificationConfig when continuous updates should use the plugin's Android foreground service:

import 'package:flutter/material.dart';

final settings = AndroidSettings(
  foregroundNotificationConfig: const ForegroundNotificationConfig(
    notificationTitle: 'Location active',
    notificationText: 'Your location is being updated.',
    notificationChannelName: 'Location updates',
    enableWakeLock: false,
    enableWifiLock: false,
    setOngoing: true,
    color: Colors.blue,
  ),
);

If a custom notification icon is needed, add the drawable to the application and provide its Android resource name:

const AndroidResource(
  name: 'location_notification',
  defType: 'drawable',
)

Then assign it to notificationIcon in the notification configuration.

The foreground notification increases the priority of the location work, but it is not a guarantee that Android will keep the application process alive. For tracking that must continue after the Flutter activity or process is destroyed, an application-level background execution strategy is required.

Other supported operations

final lastKnown = await geolocator.getLastKnownPosition();
final status = await geolocator.getLocationAccuracy();
final serviceStream = geolocator.getServiceStatusStream();
final openedAppSettings = await geolocator.openAppSettings();
final openedLocationSettings = await geolocator.openLocationSettings();

getLastKnownPosition may return null when Android has no cached location. getServiceStatusStream emits ServiceStatus.enabled and ServiceStatus.disabled as the device location service changes.

Common errors

  • LocationServiceDisabledException: enable the device location service and retry.
  • PermissionDeniedException: explain the permission requirement and request permission again when appropriate.
  • PermissionRequestInProgressException: wait for the current permission request to finish before starting another one.
  • PermissionDefinitionsNotFoundException: add at least ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION to the application manifest.
  • ActivityMissingException: call activity-dependent operations while the Flutter plugin has an attached Android activity.
  • AlreadySubscribedException: cancel the existing position subscription before creating another location stream.

Example project

The example/ directory contains a complete Android sample showing permission handling, current and last-known positions, service status, live updates, Android settings, and foreground notification configuration.

Run it with:

cd example
flutter pub get
flutter run

License

This project is distributed under the MIT License. See LICENSE.

Libraries

geolocator_android
ym_geolocator_android