Skip to main content

Geolocator

Access device location services in your Flet app using the flet-geolocator extension. The control wraps Flutter's geolocator package and exposes async helpers for permission checks and position streams.

Platform Support​

PlatformWindowsmacOSLinuxiOSAndroidWeb
Supported✅✅✅✅✅✅

Usage​

Add flet-geolocator to your project dependencies:

uv add flet-geolocator

Requirements​

The below sections show the required configurations for each platform.

Android​

Configuration to be made to access the device's location:

  • ACCESS_FINE_LOCATION: Allows access precise location. Will be preferred over ACCESS_COARSE_LOCATION, if both are set.
  • ACCESS_COARSE_LOCATION: Allows access approximate location.
  • ACCESS_BACKGROUND_LOCATION (optional): Allows access to location even when the app is in the background. Effective as from Android 10 (API level 29).
  • FOREGROUND_SERVICE_LOCATION (optional): Allows access to location even when the app is in the foreground. Effective as from Android 14 (API level 34).
Note
  • At least one of ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission is required to get location updates, with the former being preferred if both are set.
  • Specifying the ACCESS_COARSE_LOCATION permission results in location updates with accuracy approximately equivalent to a city block. It might take a long time (minutes) before you will get your first locations fix as ACCESS_COARSE_LOCATION will only use the network services to calculate the position of the device. More information here.
flet build apk \
  --android-permissions android.permission.ACCESS_FINE_LOCATION=true \
  --android-permissions android.permission.ACCESS_COARSE_LOCATION=true \
  --android-permissions android.permission.ACCESS_BACKGROUND_LOCATION=true \
  --android-permissions android.permission.FOREGROUND_SERVICE_LOCATION=true

See also:

iOS​

Configuration to be made to access the device's location:

flet build ipa \
  --info-plist NSLocationWhenInUseUsageDescription="Some message to describe why you need this permission..."

See also:

macOS​

Configuration to be made to access the device's location:

flet build macos \
  --info-plist NSLocationUsageDescription="Some message to describe why you need this permission..." \
  --macos-entitlements com.apple.security.personal-information.location=true

See also:

Cross-platform​

Additionally/alternatively, you can make use of our predefined cross-platform location permission bundle:

flet build <target_platform> --permissions location

Example​

from typing import Callable

import flet as ft
import flet_geolocator as ftg


async def main(page: ft.Page):
    page.scroll = ft.ScrollMode.ADAPTIVE
    page.appbar = ft.AppBar(title=ft.Text("Geolocator Tests"))

    def handle_position_change(e: ftg.GeolocatorPositionChangeEvent):
        page.add(ft.Text(f"New position: {e.position.latitude} {e.position.longitude}"))

    def get_dialog(handler: Callable):
        return ft.AlertDialog(
            adaptive=True,
            title="Opening Location Settings...",
            content=ft.Text(
                "You are about to be redirected to the location/app settings. "
                "Please locate this app and grant it location permissions."
            ),
            actions=[ft.TextButton("Take me there", on_click=handler)],
            actions_alignment=ft.MainAxisAlignment.CENTER,
        )

    def show_snackbar(message):
        page.show_dialog(ft.SnackBar(ft.Text(message)))

    async def handle_permission_request(e: ft.Event[ft.OutlinedButton]):
        p = await geo.request_permission(timeout=60)
        page.add(ft.Text(f"request_permission: {p}"))
        show_snackbar(f"Permission request sent: {p}")

    async def handle_get_permission_status(e: ft.Event[ft.OutlinedButton]):
        p = await geo.get_permission_status()
        show_snackbar(f"Permission status: {p}")

    async def handle_get_current_position(e: ft.Event[ft.OutlinedButton]):
        p = await geo.get_current_position()
        show_snackbar(f"Current position: ({p.latitude}, {p.longitude})")

    async def handle_get_last_known_position(e):
        p = await geo.get_last_known_position()
        show_snackbar(f"Last known position: ({p.latitude}, {p.longitude})")

    async def handle_location_service_enabled(e):
        p = await geo.is_location_service_enabled()
        show_snackbar(f"Location service enabled: {p}")

    async def handle_open_location_settings(e: ft.Event[ft.OutlinedButton]):
        p = await geo.open_location_settings()
        page.pop_dialog()
        if p is True:
            show_snackbar("Location settings opened successfully.")
        else:
            show_snackbar("Location settings could not be opened.")

    async def handle_open_app_settings(e: ft.Event[ft.OutlinedButton]):
        p = await geo.open_app_settings()
        page.pop_dialog()
        if p:
            show_snackbar("App settings opened successfully.")
        else:
            show_snackbar("App settings could not be opened.")

    location_settings_dlg = get_dialog(handle_open_location_settings)
    app_settings_dlg = get_dialog(handle_open_app_settings)

    geo = ftg.Geolocator(
        configuration=ftg.GeolocatorConfiguration(
            accuracy=ftg.GeolocatorPositionAccuracy.LOW
        ),
        on_position_change=handle_position_change,
        on_error=lambda e: page.add(ft.Text(f"Error: {e.data}")),
    )

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Row(
                        wrap=True,
                        controls=[
                            ft.OutlinedButton(
                                content="Request Permission",
                                on_click=handle_permission_request,
                            ),
                            ft.OutlinedButton(
                                content="Get Permission Status",
                                on_click=handle_get_permission_status,
                            ),
                            ft.OutlinedButton(
                                content="Get Current Position",
                                on_click=handle_get_current_position,
                            ),
                            ft.OutlinedButton(
                                content="Get Last Known Position",
                                visible=not page.web,
                                on_click=handle_get_last_known_position,
                            ),
                            ft.OutlinedButton(
                                content="Is Location Service Enabled",
                                on_click=handle_location_service_enabled,
                            ),
                            ft.OutlinedButton(
                                content="Open Location Settings",
                                visible=not page.web,  # (1)!
                                on_click=lambda e: page.show_dialog(
                                    location_settings_dlg
                                ),
                            ),
                            ft.OutlinedButton(
                                content="Open App Settings",
                                visible=not page.web,  # (1)!
                                on_click=lambda e: page.show_dialog(app_settings_dlg),
                            ),
                        ],
                    )
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Description​

A control that allows you to fetch GPS data from your device.

Inherits: Service

Properties

Events

Methods

Properties​

configurationclass-attributeinstance-attribute​

configuration: Optional[GeolocatorConfiguration] = None

Some additional configuration.

positionclass-attributeinstance-attribute​

position: Optional[GeolocatorPosition] = field(default=None, init=False)

The current position of the device. (read-only)

Starts as None and will be updated when the position changes.

Events​

on_errorclass-attributeinstance-attribute​

on_error: Optional[ControlEventHandler[Geolocator]] = None

Fires when an error occurs.

The data property of the event handler argument contains information on the error.

on_position_changeclass-attributeinstance-attribute​

on_position_change: Optional[EventHandler[GeolocatorPositionChangeEvent]] = None

Fires when the position of the device changes.

Methods​

distance_betweenasync​

distance_between(start_latitude: Number, start_longitude: Number, end_latitude: Number, end_longitude: Number)

Calculates the distance between the supplied coordinates in meters.

The distance between the coordinates is calculated using the Haversine formula (see https://en.wikipedia.org/wiki/Haversine_formula).

Parameters:

  • start_latitude (Number) - The latitude of the starting point, in degrees.
  • start_longitude (Number) - The longitude of the starting point, in degrees.
  • end_latitude (Number) - The latitude of the ending point, in degrees.
  • end_longitude (Number) - The longitude of the ending point, in degrees.

Returns:

  • Number - The distance between the coordinates in meters.

get_current_positionasync​

get_current_position(configuration: Optional[GeolocatorConfiguration] = None)

Gets the current position of the device with the desired accuracy and settings.

Note

Depending on the availability of different location services, this can take several seconds. It is recommended to call the get_last_known_position method first to receive a known/cached position and update it with the result of the get_current_position method.

Parameters:

Returns:

get_last_known_positionasync​

get_last_known_position()

Gets the last known position stored on the user's device. The accuracy can be defined using the configuration property.

Returns:

Raises:

get_permission_statusasync​

get_permission_status()

Gets which permission the app has been granted to access the device's location.

Returns:

is_location_service_enabledasync​

is_location_service_enabled()

Checks if location service is enabled.

Returns:

  • bool - True if location service is enabled, False otherwise.

open_app_settingsasync​

open_app_settings()

Attempts to open the app's settings.

Returns:

  • bool - True if the app's settings were opened successfully, False otherwise.

Raises:

open_location_settingsasync​

open_location_settings()

Attempts to open the device's location settings.

Returns:

  • bool - True if the device's settings were opened successfully, False otherwise.

Raises:

request_permissionasync​

request_permission()

Requests the device for access to the device's location.

Returns: