Skip to main content

GPS location tracking

Overland GPS webhook receiver for location tracking with place detection and visit logging.

Sharing with a room​

Ask “Share my location here” in a web room, Talk group or Baileys WhatsApp group to post one observation. This grants no ongoing access. From a private chat, “Share my location with Hiking” asks for approval of the exact message before posting it. A retry keeps the observation you approved even if your phone has moved.

“Share roughly where I am” shares an approximate area. Exact sharing is the default: a measured point with accuracy and observed time. Area sharing rounds both coordinates to two decimal places before returning them or building the map link, roughly a kilometre north/south and less east/west away from the equator. It omits precise accuracy and saved-place names. This is an approximate area, not an anonymity guarantee. Map links open OpenStreetMap when a recipient chooses to follow them. Sharing never reverse-geocodes the point.

For continuing access, ask “Let this room see my location for an hour.” You receive a private preview naming the room, the readers (all of them up to five; with more, three and a count of the rest), precision and duration, either in your private chat or your notifications. Nothing activates until you approve. Durations are 5 minutes through 24 hours, measured from approval; a request for continuing sharing without a duration proposes an hour for you to approve. Only rooms whose readers are known configured users support timed sharing. Email threads do not support either sharing mode.

While your permission is active, a member can ask “Where is Alice?” or “Where is everyone?” in that room. They do not need their own tracker enabled. Answers contain only active sharers, and only the small location projection: no history, saved places, Wi-Fi, battery or visit details. A permission applies to one room, even if several rooms belong to the same group. It starts no tracker and sends no periodic messages.

A current observation must come from the phone, be at most 15 minutes old and have usable accuracy within the configured limit. Imported Garmin tracks do not qualify. A declared point is labeled as declared. With no usable fix, the answer says no fresh location is available without an older coordinate or timestamp. You may explicitly request a last-known observation for a one-time share, up to 24 hours old; it remains labeled “Last known.” An approved delayed post retains its observed time and is never relabeled “now.”

Ask “What am I sharing?” to list your permissions, or “Stop sharing my location” to stop in the current room. “Stop sharing everywhere” also cancels pending approvals. Stop takes effect without confirmation and works when your tracker is disabled. Reader changes, a transport binding change, archiving the room or switching the bot off end its shares; rejoining or reopening requires fresh approval. Disabling your location module suspends reads until re-enabled or the original expiry; stop revokes the permission permanently.

Stop prevents later reads. A stop committed before a query's final permission check removes that location from its result. A result that already passed that check may still be delivered. Stop cannot erase earlier messages, screenshots or locations people remember.

The skill commands are location share [--room ROOM] [--precision exact|area] [--last-known] [--map auto|off] --request-key KEY, location share --for 1h --request-key KEY, location sharing and location unshare [--room ROOM | --all]. --map off applies to one-time shares and is refused with --for. Room members query with room location --user USER [--map auto|off] or room locations, and can always stop through room location-stop [--all]. Reads have no room override and never use old transcript answers as current observations.

Maps​

A one-time share comes with a map of the same observation, and so does an answer to “Where is Alice?” about one person. It shows nothing the text does not already say: a pin with its accuracy circle for an exact share, or a shaded square covering the rounded area, with the observed time and the map's attribution. The map is attached only when the answer contains the share's map link unchanged, so an answer that leaves the link out has no map. “Where is everyone?” has none.

  • Web rooms show the map as a card under the answer that you can pan and zoom. Your browser loads the tiles from the map provider the web UI uses. If the map cannot load, the card shrinks to its text line and link.
  • Talk rooms get a 640 × 360 picture shared into the room after the text.
  • Baileys WhatsApp groups get the picture with the answer as its caption. One picture goes with each message, so a second map in the same answer is not sent.
  • SMS, email and the WhatsApp Cloud API get no map, only the text and link.

A room bound to both Talk and a WhatsApp group gets the picture once, on Talk. The picture is drawn by the browser service from a page Istota sends it, and that page fetches only map tiles; it never calls back into Istota. Without the browser service, or when drawing fails or times out, the text and link go out alone and nothing is retried. An approved post from your private chat says in its preview that a map will be posted with it and draws it from the observation you approved; if Talk or the WhatsApp group then gets no picture, because drawing failed or there is no browser service, your private notice says the map was unavailable. A post into a web-only room needs no picture, since the card is the map. A posted map stays in the room after a timed share ends, like the text.

Say “no map” to share without one. A map card recorded for an answer that never carried its link is deleted after 7 days.

Architecture​

The webhook receiver (webui/webhook_receiver.py) ingests location pings from the Overland iOS/Android app. It detects transitions between named places and logs visits. On the stack its routes are served by the web service, behind the stack's nginx (webui/stack_app.py); istota serve includes them the same way.

Overland app -> POST /webhooks/location?token=... -> webui/webhook_receiver.py -> SQLite

Setup​

Enable in config:

[location]
enabled = true

istota setup writes this when you turn GPS location on.

Ingest tokens, one per device​

Every device that sends locations has its own ingest token. Tokens are rows in location_ingest_tokens in the framework istota.db, not in the per-user location.db, because the receiver has to find the user from the token before it knows which location.db to open. A row keeps the SHA-256 hash of the token and its last four characters, never the token itself. The token is a 256-bit random value, so an unsalted hash is enough, and it does not depend on ISTOTA_SECRET_KEY. The plaintext is returned once, by the request that mints it, and there is no way to read it back.

Location settings (/istota/location/settings) lists every token under Devices: the label, the token's last four characters, when it was added and when it last sent ("never" until its first batch). In the iOS app, the row for the phone you are holding is marked "This phone". Remove asks first, then deletes the row; that device's next request is refused, and no other device is affected. An account can hold 20 tokens.

Settings → Devices (/istota/settings/devices) lists the same tokens from the other side: one row per phone, joining a phone's app token with the device token it holds for quick notes, plus the code tokens and the shared token below in an "Other location trackers" card. Revoke on a phone's row removes both of its tokens in one transaction (DELETE /istota/api/devices/phones/{device_id}), so the phone stops saving quick notes and sending locations at once. Removing a row here in Location settings removes only the location token.

There are two ways to add a device.

  • One tap in the iOS app. On a phone whose tracker is not configured, the This device card shows "Turn on location tracking". It mints a token for the phone's tracker id, hands it to the tracker, asks iOS for location permission when it has not been asked yet, and starts tracking with the chosen profile once permission is granted. If the answer is not in within a minute, or permission was already denied, the tracker stays configured and stopped and the card's permission controls take over. Setting the same phone up again replaces its row in place: same row, new token, "last sent" cleared, and the old token stops working. Two accounts used in turn on one phone each get their own row.
  • A code. "Create code" on the Provision a device card mints a new token each time and shows it once, as a QR code and as the full webhook URL. Scan it with the app's "Scan a code instead" button, or paste the URL into third-party Overland. Creating a code never changes another device's token.

When the server refuses a configured phone's token (the tracker reports "token rejected", usually because the row was removed), the card says so and offers "Set up again", which mints a new token and reconfigures the tracker without starting or stopping it. Points the tracker held while refused are sent on its next send.

Ingest tokens are not tied to a web session. Signing out, a session expiring or a password change leaves a tracker running. A token stops working when it is removed from the list or when the account is disabled, on the device's next request either way. Turning the location module off for the user also stops it, but only once the receiver next reloads (a restart, a SIGHUP, or any token change), since nothing signals the receiver when a module is turned off.

The routes, all under /istota/api:

RouteDoes
GET /location/devicesLists the rows (id, kind, device_id, label, token_tail, created_at, last_used_at), newest first, plus legacy_token, whether the shared token below exists. Never a token or a hash
POST /location/devicesMints a token. Body: kind (app or code), device_id (a UUID, required for app and refused for code) and an optional label. Returns id, token, endpoint and webhook_url with status 201
DELETE /location/devices/{id}Removes one row. 404 for a row that is not yours
DELETE /location/devices/legacyRemoves the shared token. 404 when there is none

The label has control characters removed and is trimmed. Over 64 characters after that is refused with 400 rather than cut short, and a blank label becomes "iPhone" for app or "QR code" for code. An unknown body key is a 400 naming it.

Minting refuses before it writes anything, in this order: 409 when the location module is off for the user (the receiver builds no token map for them, so the token would be refused on first use), 409 when [site] hostname is unset, 400 naming the field that is wrong, and 409 "This account already has 20 devices. Remove one first." Replacing a phone's existing row never counts against the 20. The hostname check exists because the assembled URL would otherwise be a relative path, which the phone's decoder rejects as not being https://, and the device would then blame the code rather than the configuration. In practice only istota serve on a Mac reaches it, since under Nextcloud auth a blank hostname already fails the origin check. The endpoint is always built from [site] hostname, not from the address the page was opened on. When the app is connected under a different name for the same server, the tracker refuses it with WRONG_SERVER and the card shows that message; the minted row stays in the list and can be removed.

The QR code​

A created code is rendered as a QR code the native iOS app scans, with the full webhook URL printed beside it for the third-party Overland app, which has no scanner. The payload is a small JSON envelope ({v, endpoint, token}, version 1) carrying the endpoint and the token, deliberately not the webhook URL itself: a bare https:// code is offered for opening by every generic scanner, including the iOS Camera app, which would put the token in Safari's address bar and history in exchange for a 405. The query string is stripped from the endpoint, so the token appears in the payload exactly once; the tracker sends it as a bearer header. The decoder rejects rather than repairs: a wrong version, a non-https endpoint, or anything over its size caps is refused whole rather than partially honoured. Leaving the settings page loses the code, because there is nowhere to read the token back from; the next device needs a new one.

The shared token from before per-device tokens​

Before per-device tokens each account had one token, the encrypted secret overland / ingest_token, and minting a new one cut off every device using the old. An upgrade keeps it working: the receiver still accepts it, and nothing converts it into per-device rows, since the server cannot know which devices hold it. The Devices list shows it as "Shared token (from before per-device tokens)" with a Remove button. Remove it once each device that used it has been set up again. It has no "last sent" time, because there is no row to record one on.

The location page no longer creates or rotates it, and the old POST /istota/api/settings/secrets/overland/ingest_token/generate route is gone. It can still be written by PUT /istota/api/settings/secrets/overland/ingest_token, a settings plan, or the CLI:

istota secret ensure --user alice --service overland --key ingest_token --value secret-token-here

Reloading the receiver​

The receiver holds a map from token hash to user in memory, loaded when it starts. Minting, removing a token, a web write to the shared token, and disabling or re-enabling an account (the admin page or istota auth disable|enable) each stamp a sentinel (.location_ingest_reload, beside istota.db) that the receiver stats on each ingest request and reloads from, so a removed token is refused on the very next request. Stamping is best-effort: if it fails, the change applies after the next restart. The CLI path above does not stamp it: istota secret ensure writes the secret and nothing else, so a shared token provisioned that way applies on the receiver's next restart or SIGHUP. A reload that cannot read the token table or the account list logs a warning and keeps the previous map.

A token's "last sent" time is written after a batch is stored, at most once every ten minutes per token. The write is best-effort and does not affect the response.

There is no separate receiver process to run. With [location] enabled = true the web app includes the ingest router, so the endpoint is /webhooks/location on the web app's own address and webhooks_port is unused. The image carries the location extras. The receiver loads with the web app, and a SIGHUP to the web process reloads both. The sentinel above is still what applies a token minted in the browser without either.

Tracking on the device​

The native app's tracker is configured on the phone and nowhere else. That is forced rather than chosen: one account can have two phones, so any tracker setting kept server-side would have the two devices overwriting each other's row. The This device card on /location/settings therefore talks to the app directly and renders only inside it; in a browser it says so in one line rather than disappearing, so a user who set this up on their phone can tell the section is absent by design.

What it exposes is deliberately smaller than Overland's fifteen settings:

SettingNotes
Tracking on/offReads Paused rather than On when iOS has suspended updates because the phone hasn't moved — a battery saving, so the card says so as information rather than a warning, and notes that moving resumes it. "On" beside an hours-old last-sent time and an empty queue is what a tracker that has silently died looks like, which is the one reading this card exists to make trustworthy. Stop stays available: tracking is still armed
Profile: Detailed or PlacesDetailed logs a continuous line and sends every minute, at a battery cost. Places logs arrivals and departures only and sends every five minutes. Switching while tracking re-arms in place, so it costs no gap in coverage; switching while stopped is held and applied by the next Start, since starting is the only thing that can set a profile
Permission, and a way into iOS SettingsOnly Settings.app can restore a denied Always authorization, so that is the one state where the button replaces Start/Stop rather than sitting beside it. While in use — the case the card mostly exists to catch — keeps Stop reachable and shows the prompt alongside it
Queued points, points dropped, last sent, last error, endpoint host, device idThe readout that says tracking is still alive. The failure worth preventing is tracking stopping silently and the gap being found weeks later. Only the endpoint's host is shown; the token is never echoed back
Turn on location tracking, scan a code insteadShown while the tracker is not configured. See ingest tokens
Send now, rescan code, set up againSet up again appears only when the server has refused this phone's token

Send interval and batch size are not separately exposed. The interval follows the profile — there is nothing to send every minute when fixes arrive a kilometre apart — and a numeric field with no basis for setting it invites a five-second interval and a dead battery.

Both profiles request 100 m accuracy, which is not a knob because the server drops any ping worse than accuracy_threshold_m (default 100) from place matching. A genuinely coarse profile would keep storing pings — the map would still fill in — while quietly ceasing to detect being anywhere.

The card is gated on the app's version, and the two halves are gated separately: tracking needs shell 0.6.0, scanning a code needs 0.7.0. A 0.6.0 app therefore gets the status card and the one-tap "Turn on location tracking" button, which needs no scanner, and no Scan button that would do nothing. No app update is needed for the one-tap path: it uses the same configure call a scan ends in. The gate reads the app's own IstotaApp/<version> user-agent token rather than the presence of a plugin object, so a page carrying a look-alike shim outside the app never calls through. A scan that finds nothing distinguishes three outcomes — cancelled (which says nothing, because the user chose it), a code that isn't ours, and a build too old to scan.

Places​

Named geofences stored in the places DB table. Manage via CLI or web UI:

  • CLI: learn, update, delete subcommands via python -m istota.skills.location
  • Web UI: create from discovered clusters, edit form, drag-to-reposition on map

Places have an optional notes text field for free-form annotations.

Place detection uses hysteresis (2 consecutive pings required) to avoid flapping at geofence boundaries. Pings with horizontal accuracy above accuracy_threshold_m (default 100 m) are stored but skipped for place matching. A periodic reconciler re-derives closed visits from stored pings so historical visits recover from state-machine drift. Updating a place's location or radius triggers automatic ping reassignment.

Silence is not departure​

A stationary tracker stops reporting. That is what a phone does when it has been on a desk for four hours, and it is the single most common thing to get wrong when reading a track back into visits — twice, in two different places, and both are now fixed:

  • A gap between two pings at the same place no longer splits the visit. The live state machine already required an observed ping somewhere else before closing one; the reconciler did not, and split on reconcile_grace_minutes alone, so an afternoon at home came back as four visits with the quiet stretches between them missing. Same-place pings are now one segment however long the gap. The grace period still applies to an unassigned ping, which is evidence of being somewhere else (ISSUE-329).
  • A day summary's stops end at the first later observation elsewhere, not at the last ping inside. Same reasoning one layer up, in the stop clustering the day summary renders: the last ping at a stop is where you were last seen. Departure is inferred from the first fix somewhere else, minus its estimated travel time — from the ping's recorded speed, or 30 mph where it has none — capped at six hours of inferred extension, so an overnight outage is not assigned to a stop. Both paths that build a day summary (istota-skill location day-summary and the web today view) look past the end of the requested day for that closing observation, and deliberately do not count it as one of the day's own (ISSUE-332).

The first fix's rolling cleanup also replaces closed rows that a reconstructed segment now spans, so an upgrade does not leave the old fragment overlapping the merged visit.

Database​

Location data lives in per-user SQLite files at {workspace}/location/data/location.db, not in the framework istota.db. The module package at src/istota/location/ provides resolve_for_user(user_id, config) following the same pattern as feeds and money.

Tables (per-user location.db)​

TablePurpose
location_pingsRaw GPS data (carries a source column: overland for native phone pings, garmin for imported watch tracks; and an optional client_id — see below)
placesNamed geofences with coordinates and radius
visitsDetected place visits (arrival/departure)
location_statePer-user tracking state
dismissed_clustersClusters the user chose not to save as places

Old pings are cleaned after location_ping_retention_days (default 365).

Declared points while you sit still​

A declared point is a coordinate the iOS shell asserts while the device is on the configured home SSID rather than a fix it took, marked by location_pings.wifi_zone (ISSUE-229). It is constant by construction, so re-sending it says nothing the first one did not — and the shell sent one every 60 s for as long as the device stayed put. Measured over a month, that was 26,713 of 39,319 native pings at a single coordinate, one stay running 42 hours.

The receiver now drops a declared point that adds nothing: the stay is already established by the newest three stored rows, every one of them is declared and at this same coordinate, and the newest is under 15 minutes old. Any of those failing means something happened worth recording, and an out-of-order or unparseable point is always stored. A suppressed point returns before the insert, so the place state machine does not re-run on a place it is already sitting on; visits are unaffected, since a stay is defined by when it started and by where you turn up next (ISSUE-349). The shell stops emitting the repeats in its next build; until then the server drops them on arrival.

Re-sent batches​

A client that keeps points in a queue and deletes them only once the server acknowledges the batch will re-send a batch whose response was lost. If the point's GeoJSON properties carry a client_id — a value the client mints once per point — the second delivery is recognised and writes nothing. Uniqueness is enforced by a partial index, so points without one (stock Overland, the Garmin importer) never collide with each other and genuinely repeated fixes all land.

This matters beyond a duplicate row: every ping at your current place increments the open visit's ping_count, so a re-sent batch would otherwise inflate a visit that never grew.

The two Nominatim caches (geocode_cache, reverse_geocode_cache) remain in the framework istota.db for cross-user dedup. Skill subcommands and web routes that need reverse geocoding open a second connection via location.db.with_geocode_conn(framework_db_path).

Garmin track import​

Overland (the phone tracker) is the normal source of pings, but activities recorded on a Garmin watch without the phone (watch-only runs, hikes where the phone stays packed or dies) leave gaps. scripts/import_garmin_tracks.py pulls GPS tracks for watch-recorded running / hiking / walking activities and inserts them into location.db as source='garmin' pings, only where Overland has no native coverage — native always wins.

It authenticates through the shared Garmin connection (Settings → Connections; the same credentials the health module uses), so connect Garmin once and both features work. The dedup is spatiotemporal: a Garmin point is dropped only when a native ping exists within both a time band (--guard-band, default 300 s) and a distance band (--guard-radius, default 150 m) of it — so a phone left at home never shadows a run happening elsewhere. Declared points (wifi_zone = 1) are not counted as coverage at all: those are a coordinate the phone asserts while it is on the home SSID, not a fix it took, so they record nothing to shadow with. Left in, they deleted real track: a run starting and ending at the door passes within --guard-radius of the parked phone twice, and a measured 22-minute run lost its first 151 m and its last 171 m that way (ISSUE-348). A phone that is genuinely stationary and taking real fixes is the same trap one step narrower and is deliberately not handled — those rows are at least measurements. Imported points are placeless breadcrumbs (place_id NULL) that show on the map and in history but don't create place visits. Re-running is idempotent (evict-then-reinsert per activity), and a late Overland upload for a gap-filled window evicts the now-covered imports on the next run.

The importer core lives in istota.location.garmin_import (import_tracks()), shared by three access points:

  • Web button — "Import GPS tracks" on the Garmin card (Settings → Connections) calls POST /istota/api/garmin/import-tracks (gated on the location module), which runs the importer inline and reports how many points it added.
  • Assistant / chat — the location import-garmin-tracks skill subcommand. Because the sandbox can write location.db but not decrypt the Garmin tokens (the master key is stripped), a sandboxed call delegates: it writes a task_<id>_garmin_import.json deferred op and the scheduler runs the import in-process post-task, then notifies the user with the result. An import run by a scheduled job notifies only when it fails. An operator shell that has ISTOTA_SECRET_KEY runs it directly instead.
  • CLI / cron — scripts/import_garmin_tracks.py, a thin wrapper over the same module (below).
# Dry-run (read-only) — see what would import over the last 30 days
scripts/import_garmin_tracks.py --user alice --days-back 30 --dry-run

# Nightly rolling import
scripts/import_garmin_tracks.py --user alice --days-back 7

Environment / cron. The script decrypts the Garmin token blob, so it needs ISTOTA_DB_PATH (the framework istota.db — also used to resolve the per-user location.db, so the script is working-directory independent) and ISTOTA_SECRET_KEY in its environment, and must run in the real scheduler/cron environment where location.db is reachable (never inside a task sandbox, where the database directories are masked out). Because istota's CRON.md command: jobs deliberately strip *_SECRET/*_TOKEN vars, wire the nightly run as a system cron entry or systemd timer that sources the service EnvironmentFile and sets ISTOTA_DB_PATH, not as a CRON.md job. --dry-run is read-only and safe to run anywhere the env is available.

Network access​

The webhook receiver must be reachable from the Overland app on your phone. Two approaches:

Public hostname (recommended): the stack's nginx already routes /webhooks/ to the web service, so in direct ingress, or proxied behind a reverse proxy that forwards the whole hostname, there is nothing more to configure. Point Overland at https://{your-hostname}/webhooks/location with your ingest token.

VPN (alternative): if you don't want to expose the endpoint publicly, give the stack a hostname that resolves only inside a WireGuard or Tailscale network, and connect your phone to it. This keeps the endpoint off the public internet but requires the VPN to be active for location tracking to work. QR provisioning still needs an https:// endpoint and [site] hostname; with plain HTTP, the URL has to be typed into stock Overland by hand.

A public hostname with TLS is the simpler arrangement, since it also covers the web UI. The endpoint is authenticated by a device's ingest token (or the shared token from before per-device tokens), supplied either as a ?token= query parameter (what Overland sends) or as an Authorization: Bearer header (what the native tracker sends). A missing token is a 401 and an unknown one a 403. Public exposure is safe as long as TLS is enabled and tokens are kept secret.

Web interface​

The web interface provides location pages:

  • Today view: current position, day summary, trips, elevation profile
  • History: date picker, activity filter, heatmap, elevation profile
  • Places: discover unknown clusters (with dismiss option), create/edit/delete places, visit statistics

Following the timezone on travel​

user_profiles.timezone drives the User timezone: prompt header, and through it every briefing, calendar read and scheduled prompt. The scheduler can keep it in step with where the user actually is: once the newest ping and a ping at least an hour older resolve to the same IANA zone, sit within 100 km of each other, and that zone puts the clock somewhere other than the stored one does, the profile is updated and the user is told.

It is opt-in per user — timezone_follow_location on the profile, the "Update timezone when I travel" checkbox beside the timezone field in Settings, off by default. The setting being rewritten is one the user chose, so it is something they switch on and an event they are notified about, rather than an inference made quietly. It also needs the location module enabled and the location extra installed (timezonefinder, which resolves coordinates offline — no network call, and the user's position is not sent anywhere).

The distance test, not the hour, is what keeps a journey from moving the timezone. "Has been in this zone for an hour" is true of a plane over the Midwest: a continental flight spends over two hours above a single zone, so a dwell-only rule would set the timezone to whatever is being flown over and then set it again on landing. Requiring that the two samples are also near each other asks the question actually intended — have you stayed somewhere. Open water is covered separately: it resolves to an Etc/GMT±N offset rather than a place, and those are rejected outright.

Three further guards. A track that has gone stale (nothing within two hours) is ignored, since yesterday's position says nothing about today. A ping with no accuracy figure, or one worse than [location] accuracy_threshold_m, is not used — an imported watch track carries no accuracy at all, and a junk fix can land across a border. And a zone that merely renames the stored one (US/Pacific against America/Los_Angeles, both of which Nextcloud seeds) is not a move, so it is compared by the wall clock it produces rather than by name.

The change is recorded, and the same zone is not written again for 24 hours. Detection compares where you are against what is stored and remembers nothing by itself, so without that record a user who prefers home time abroad and sets it back by hand would be overridden on the next pass, and again on the one after.