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#

Platform	Windows	macOS	Linux	iOS	Android	Web
Supported	✅	✅	✅	✅	✅	✅

Usage#

Add flet-geolocator to your project dependencies:

uvpip

uv add flet-geolocator

pip install flet-geolocator  # (1)!

After this, you will have to manually add this package to your requirements.txt or pyproject.toml.

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 buildpyproject.toml

flet build apk \
  --android-permissions android.permission.ACCESS_FINE_LOCATION=True \
      android.permission.ACCESS_COARSE_LOCATION=True \
      android.permission.ACCESS_BACKGROUND_LOCATION=True \
      android.permission.FOREGROUND_SERVICE_LOCATION=True

[tool.flet.android.permission]
"android.permission.ACCESS_FINE_LOCATION" = true
"android.permission.ACCESS_COARSE_LOCATION" = true
"android.permission.ACCESS_BACKGROUND_LOCATION" = true
"android.permission.FOREGROUND_SERVICE_LOCATION" = true

iOS#

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

flet buildpyproject.toml

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

[tool.flet.ios.info]
NSLocationWhenInUseUsageDescription = "Some message to describe why you need this permission..."

macOS#

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

flet buildpyproject.toml

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

[tool.flet.macos.info]
NSLocationUsageDescription = "Some message to describe why you need this permission..."

[tool.flet.macos.entitlement]
"com.apple.security.personal-information.location" = true

Cross-platform#

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

flet buildpyproject.toml

flet build <target_platform> --permissions location

[tool.flet]
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.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),
                ),
            ],
        )
    )


ft.run(main)

Description#

Inherits: Service

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

Properties

configuration(GeolocatorConfiguration | None) –

Some additional configuration.
position(GeolocatorPosition | None) –

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

Events

on_error(ControlEventHandler[Geolocator] | None) –

Fires when an error occurs.
on_position_change(EventHandler[GeolocatorPositionChangeEvent] | None) –

Fires when the position of the device changes.

Methods

distance_between –

Calculates the distance between the supplied coordinates in meters.
get_current_position –

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

Gets the last known position stored on the user's device.
get_permission_status –

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

Checks if location service is enabled.
open_app_settings –

Attempts to open the app's settings.
open_location_settings –

Attempts to open the device's location settings.
request_permission –

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

Properties#

configuration `class-attribute` `instance-attribute` #

configuration: GeolocatorConfiguration | None = None

Some additional configuration.

position `class-attribute` `instance-attribute` #

position: GeolocatorPosition | None = 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_error `class-attribute` `instance-attribute` #

on_error: ControlEventHandler[Geolocator] | None = None

Fires when an error occurs.

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

on_position_change `class-attribute` `instance-attribute` #

on_position_change: (
    EventHandler[GeolocatorPositionChangeEvent] | None
) = None

Fires when the position of the device changes.

Methods#

distance_between `async` #

distance_between(
    start_latitude: Number,
    start_longitude: Number,
    end_latitude: Number,
    end_longitude: Number,
) -> 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_position `async` #

get_current_position(
    configuration: GeolocatorConfiguration | None = None,
) -> GeolocatorPosition

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:

configuration (GeolocatorConfiguration | None, default: None ) –

Additional configuration for the location request. If not specified, then the Geolocator.configuration property is used.

Returns:

GeolocatorPosition –

The current position of the device as a GeolocatorPosition.

get_last_known_position `async` #

get_last_known_position() -> GeolocatorPosition

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

Returns:

GeolocatorPosition –

The last known position of the device as a GeolocatorPosition.

Raises:

FletUnsupportedPlatformException –

If invoked on a web platform.

get_permission_status `async` #

get_permission_status() -> GeolocatorPermissionStatus

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

Returns:

GeolocatorPermissionStatus –

The status of the permission.

is_location_service_enabled `async` #

is_location_service_enabled() -> bool

Checks if location service is enabled.

Returns:

bool –

True if location service is enabled, False otherwise.

open_app_settings `async` #

open_app_settings() -> bool

Attempts to open the app's settings.

Returns:

bool –

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

Raises:

FletUnsupportedPlatformException –

If invoked on a web platform.

open_location_settings `async` #

open_location_settings() -> bool

Attempts to open the device's location settings.

Returns:

bool –

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

Raises:

FletUnsupportedPlatformException –

If invoked on a web platform.

request_permission `async` #

request_permission() -> GeolocatorPermissionStatus

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

Returns:

GeolocatorPermissionStatus –

The status of the permission request.

Geolocator#

Platform Support#

Usage#

Requirements#

Android#

iOS#

macOS#

Cross-platform#

Example#

Description#

Properties#

configuration class-attribute instance-attribute #

position class-attribute instance-attribute #

Events#

on_error class-attribute instance-attribute #

on_position_change class-attribute instance-attribute #

Methods#

distance_between async #

get_current_position async #

get_last_known_position async #

get_permission_status async #

is_location_service_enabled async #

open_app_settings async #

open_location_settings async #

request_permission async #

configuration `class-attribute` `instance-attribute` #

position `class-attribute` `instance-attribute` #

on_error `class-attribute` `instance-attribute` #

on_position_change `class-attribute` `instance-attribute` #

distance_between `async` #

get_current_position `async` #

get_last_known_position `async` #

get_permission_status `async` #

is_location_service_enabled `async` #

open_app_settings `async` #

open_location_settings `async` #

request_permission `async` #