pyxpo-location

Where the phone is: position, live updates, compass heading and address lookup for pyxpo apps, written in Python. The API follows expo-location. iOS uses Core Location. Android uses the platform LocationManager (no Google Play services), the accelerometer and magnetometer for the heading, and Geocoder for addresses.

import pyxpo_location as Location

perm = await Location.request_foreground_permissions_async()
if perm["granted"]:
    loc = await Location.get_current_position_async(accuracy=Location.Accuracy.HIGH)
    print(loc["coords"]["latitude"], loc["coords"]["longitude"])

Features

• Permissions with expo's response shape, plus which accuracy the user granted ("fine" or "coarse" on Android, "whenInUse" or "always" on iOS). A hook reads or asks on mount.
• Current and last known position with six accuracy levels from about 3 km to the best the device can do.
• Live updates with watch_position_async, tuned by accuracy, time_interval and distance_interval.
• Compass heading, once or as a stream.
• Geocoding both ways: an address to coordinates, and coordinates to a street address.
• Provider status: are location services on, is GPS or network location available.
• Honest limits: background updates and geofencing raise NotSupportedError, because pyxpo has no task manager yet.
• Typed: ships py.typed. Every function has its expo spelling too (getCurrentPositionAsync, {"distanceInterval": 10}).

Contents

Platform support

Requires Python 3.9+ and pyxpo>=0.1.0a2.

Install

pip install pyxpo-location

[tool.pyxpo]
modules = ["location"]

# Optional: the text of the iOS permission prompts.
[tool.pyxpo.module_options.location]
locationWhenInUsePermission = "Show places near you."

Rebuild the app after adding the module (pyxpo run android or pyxpo run ios). On Android the module adds ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION and marks the location hardware as optional.

Quick start

import pyxpo_location as Location
from pyxpo import Button, Text, View, component, use_async, use_state


@component
def Here():
    wanted, set_wanted = use_state(0)
    place, set_place = use_state("Not yet")

    async def locate():
        if wanted == 0:
            return
        perm = await Location.request_foreground_permissions_async()
        if not perm["granted"]:
            set_place("Permission denied")
            return
        loc = await Location.get_current_position_async(accuracy=Location.Accuracy.HIGH)
        c = loc["coords"]
        set_place("%.4f, %.4f" % (c["latitude"], c["longitude"]))

    use_async(locate, [wanted])
    return View(Text(place), Button("Locate me", lambda: set_wanted(wanted + 1)))

Tip: use_async(fn, deps) awaits a real async def when the dependencies change. A button that must start async work bumps a counter in state, and the counter is a dependency, as above.

Permissions

perm = await Location.get_foreground_permissions_async()       # does not ask
perm = await Location.request_foreground_permissions_async()   # asks if undetermined
status, request, get = Location.use_foreground_permissions()    # a hook

The response is expo's, {"status", "granted", "canAskAgain", "expires"}, plus:

An Android user can allow only approximate location, so granted can be true with "coarse". Positions are then less precise.

Current position

loc = await Location.get_current_position_async(accuracy=Location.Accuracy.BALANCED)
last = await Location.get_last_known_position_async(max_age=60_000, required_accuracy=100)

A location is {"coords": {"latitude", "longitude", "altitude", "accuracy", "altitudeAccuracy", "heading", "speed"}, "timestamp", "mocked"}. Values the device does not know are None. timestamp is milliseconds since 1970. mocked is Android only.

Higher accuracy costs more battery. get_last_known_position_async returns None when there is no cached location, or it is older than max_age ms, or less exact than required_accuracy metres.

Live updates

sub = await Location.watch_position_async(
    {"accuracy": Location.Accuracy.BALANCED, "distanceInterval": 10},
    lambda loc: print(loc["coords"]),
)
...
sub.remove()

Pass error_handler to hear about failures. sub.remove() stops the updates and is safe to call twice. Start the watch from use_async (or a function that you stop in a cleanup) and remove it when the screen goes away, or it keeps draining the battery.

Heading

h = await Location.get_heading_async()      # {"trueHeading", "magHeading", "accuracy"}
sub = await Location.watch_heading_async(lambda h: print(h["magHeading"]))

Values are degrees. trueHeading is -1 until the location is known. A device without a compass, and the iOS Simulator, raise an error instead.

Geocoding

spots = await Location.geocode_async("1600 Amphitheatre Parkway, Mountain View")
places = await Location.reverse_geocode_async({"latitude": 48.8584, "longitude": 2.2945})

geocode_async returns [{"latitude", "longitude", "altitude", "accuracy"}]. reverse_geocode_async returns addresses with name, street, streetNumber, district, city, subregion, region, postalCode, country, isoCountryCode, timezone and formattedAddress. Both need a network. An empty address raises ValueError, and so does a latitude or longitude that is not a number or out of range.

Provider status

Not supported yet

start_location_updates_async, stop_location_updates_async, has_started_location_updates_async and the matching geofencing functions need a background task manager, which pyxpo does not have yet. They raise NotSupportedError, and is_background_location_available_async() returns False. Use watch_position_async while the app is open.

Errors

Web and desktop

Nothing is available there. has_services_enabled_async() returns False, and the other functions raise NotSupportedError. For a web build, let the user type an address and use your own geocoding service.

Recipe: a "find stores near me" screen

Ask once, show the place, and fall back to the last known position when a fresh fix is slow.

import pyxpo_location as Location
from pyxpo import Button, Text, View, component, use_async, use_state


@component
def NearMe():
    tries, set_tries = use_state(1)
    text, set_text = use_state("Looking...")

    async def find():
        perm = await Location.request_foreground_permissions_async()
        if not perm["granted"]:
            set_text("Allow location to see stores near you.")
            return
        try:
            loc = await Location.get_current_position_async(accuracy=Location.Accuracy.BALANCED)
        except Exception:
            loc = await Location.get_last_known_position_async(max_age=10 * 60_000)
        if loc is None:
            set_text("No position yet. Is location on?")
            return
        c = loc["coords"]
        where = await Location.reverse_geocode_async(
            {"latitude": c["latitude"], "longitude": c["longitude"]})
        city = where[0].get("city") if where else None
        set_text("Stores near %s" % (city or "you"))

    use_async(find, [tries])
    return View(Text(text), Button("Try again", lambda: set_tries(tries + 1)))

Production checklist

• Ask for location after the user picks a feature that needs it, not at launch, and explain why first.
• locationWhenInUsePermission says why you need it, in the user's words.
• You handle denied, approximate-only (Android "coarse") and services-off cases.
• Accuracy is no higher than you need. BALANCED is enough for "near me".
• Every watch_* subscription is removed when the screen goes away.
• You do not promise tracking with the app closed.
• Your privacy policy says what you do with the position.
• You tested on a real phone, not only an emulator with a fixed point.

Testing

Run unit tests on the desktop host by replacing the native call:

import asyncio

import pyxpo_location as Location


def test_current_position(monkeypatch):
    async def fake_call(*args, **kwargs):
        return {"coords": {"latitude": 52.52, "longitude": 13.4, "accuracy": 5}, "timestamp": 0}

    monkeypatch.setattr(Location, "_native", lambda: None)
    monkeypatch.setattr(Location, "call", fake_call)

    loc = asyncio.run(Location.get_current_position_async(accuracy=Location.Accuracy.HIGH))
    assert loc["coords"]["latitude"] == 52.52

Argument checks need no fake: Location.get_current_position_async(accuracy=9) raises ValueError before any native call.

Troubleshooting

FAQ

Does it need Google Play services? No. Android uses the platform LocationManager.

Can it track in the background? Not yet. See Not supported yet.

Can I get the address of a place? Yes, with reverse_geocode_async.

Is the heading true north? trueHeading is, once the location is known. magHeading is magnetic north.

Why does watch_position_async take both a dict and keywords? The dict is expo's shape. Keywords are the Python shape. Both work.

API reference

Permissions

Position, heading and geocoding

Types

License

MIT