Skip to content

Locations & history

There are three ways to read a location out of Beekon:

  • Live stream: locations. Real time, no replay: a new subscriber gets only locations admitted after it subscribes. It emits only while the app process is alive.
  • One-shot fix: getCurrentLocation(timeout, accuracy). A single location now, independent of tracking.
  • History: getLocations(from, to). Reads the on-device SQLite database, which survives process death.

A Location has the same 16 fields on all four platforms. On this page, a fix is the raw reading from the OS provider; a location is a fix that passed the gate and was stored.

  • latitude, longitude and timestamp are always present: the OS can’t return a fix without them.
  • accuracy, speed, bearing and altitude are optional. null means the OS did not measure that field; 0 always means the OS reported zero.
  • Every location also carries a stable id, derived metadata (quality, trigger, motion, activity, isMock) and the battery state when it was recorded (batteryPercent, isCharging, powerSaveMode).
id, latitude, longitude, timestamp, // always present
accuracy?, speed?, bearing?, altitude?, // null when unreported
quality, trigger, motion, activity, isMock, // derived metadata
batteryPercent?, isCharging?, powerSaveMode? // record-time battery,
// null when unknown
FieldUnitNotes
idopaquestable identifier of the location
latitude, longitudedegrees (WGS-84)always present
accuracymetres (horizontal, 1σ)null when the OS did not report
speedmetres/secondnull when the OS did not report (e.g. stationary)
bearingdegrees, [0, 360) clockwise from true northnull when unreported; direction of travel, not heading
altitudemetres above WGS-84 ellipsoidnull when unreported or vertical accuracy invalid
timestampwall-clockThe OS provider’s fix time, not the time Beekon received it
qualityLocationQualitythe SDK’s own check of the fix; values below
triggerLocationTriggerwhy the location was captured; values below
motionMotionStatewhether the device was moving; values below
activityActivityType, nullablethe detected activity; null unless detectActivity is on and granted. See Activity detection
isMockbooleanwhether the OS flagged the location as mock/simulated
batteryPercentinteger 0…100battery level when the location was recorded (a cached OS sample, never polled); null when unknown (simulator, monitoring unavailable)
isChargingbooleancharging (incl. full-on-charger) at record time; null when unknown
powerSaveModebooleanBattery Saver / Low Power Mode active at record time; null when unknown

Casing follows the platform: Android LowAccuracy, iOS .lowAccuracy, Flutter LocationQuality.lowAccuracy, React Native 'lowAccuracy'. These enums may gain values in a minor release, so give every switch an else or default branch.

quality (LocationQuality). Every location is delivered, whatever its quality; this marks the suspect ones.

ValueMeaning
okThe fix passed the accuracy and speed checks.
lowAccuracyHorizontal accuracy was worse than 100 m.
implausibleSpeedThe speed implied by the distance from the previous stored location was above 300 m/s: a jump no vehicle makes.

trigger (LocationTrigger).

ValueMeaning
intervalA scheduled fix that passed the time and distance gate.
motionCaptured because the device started or stopped moving.
checkInA check-in recorded while stationary, with whenStationary set to pauseWithCheckIns.
geofenceCaptured because the device crossed a geofence boundary.
manualReturned by getCurrentLocation.

motion (MotionState).

ValueMeaning
movingThe device was moving.
stationaryThe device was stationary.
unknownNot determined: early in a session, before motion detection has settled, or with whenStationary set to keepTracking, which turns motion detection off.

The upload payload spells quality and trigger in snake case (low_accuracy, check_in); see Payload.

Beekon does not modify locations. There is no Kalman filter, outlier rejection, speed clamp or minimum-accuracy filter. What the OS provider produces is what you get on the stream and in history.

The one exception is in the Location constructor: invalid values (NaN, Infinity, a bearing outside [0, 360)) become null. Beekon drops values that can’t be meaningful; it never invents one. As a result, neighbouring locations can disagree a lot (between tall buildings, in a tunnel, at a cold start). Show that to users through accuracy rather than hiding it.

The live stream is hot and does not replay: each subscriber receives the locations admitted after it subscribed, so read getLocations(...) for anything earlier. On Android it is a SharedFlow with replay = 0 and a 64-location buffer (DROP_OLDEST: a slow consumer drops old emissions but never blocks the producer). On iOS each access to locations returns its own AsyncStream, buffering the newest 64. state and syncStatus (and authChanges, once a token exists) replay their current value to each new subscriber; locations, geofenceEvents and logs don’t.

Beekon.locations.collect { loc ->
Log.d("beekon", "${loc.latitude}, ${loc.longitude} acc=${loc.accuracy ?: "—"}m")
}

The live stream emits only while the app process is alive. For locations recorded while the process was dead, read history.

A common case is dropping low-accuracy locations when drawing a map. Do it in your own stream consumer; history still records every location unfiltered.

Beekon.locations
.filter { (it.accuracy ?: Double.MAX_VALUE) <= 25.0 }
.collect { /* render */ }

When you need a location at one moment (for example, when a trip starts) without starting tracking, call getCurrentLocation and await it. It works whether or not a session is running, and never starts, stops or changes one. The result goes to the caller only: it is not stored and does not appear on the live stream. It is tagged trigger = Manual.

It returns null only when no usable fix arrives within the timeout (default 15 s). A failed precondition throws instead, so you can tell “ask for permission” apart from “try again”. The reason is one of:

ReasonMeaning
PermissionDeniedLocation permission is missing (on iOS, also denied or restricted).
LocationServicesDisabledSystem location services are off. The user can turn them on.
UnavailableLocation can’t be read on this device. On Android, Google Play services is missing or out of date.

Casing follows the platform: Android LocationUnavailableReason.PermissionDenied, iOS .permissionDenied, Flutter LocationUnavailableReason.permissionDenied. React Native rejects with a BeekonError whose kind is 'permissionDenied', 'locationServicesDisabled' or 'locationUnavailable'.

On iOS 15 and 16, getCurrentLocation ignores timeout and accuracy: it makes one standard Core Location request with about 10 m accuracy and gives up after 10 seconds. The parameters apply from iOS 17.

val fix = Beekon.getCurrentLocation(
timeoutMs = 15_000,
accuracy = AccuracyMode.High,
)
if (fix != null) Log.d("beekon", "now at ${fix.latitude}, ${fix.longitude}")
// null ⇒ timed out;
// throws BeekonException.LocationUnavailable on a precondition failure

Every location that passes the gate is written to a SQLite database owned by the native library. The schema, retention and write rules are the same on both platforms; only the engine differs (Room on Android, GRDB on iOS). The write happens in the native location callback, so it does not depend on the Dart or JS runtime being alive.

Each row is one stored location. The table shows the core columns; the database has more (such as the id, motion, activity, quality, session, user id and battery fields).

ColumnTypeMeaning
tsINTEGER NOT NULLUnix milliseconds (timestamp from the OS provider)
latREAL NOT NULLDegrees
lngREAL NOT NULLDegrees
accuracyREAL (nullable)Metres, horizontal 1σ; NULL when unreported
speedREAL (nullable)Metres/second; NULL when unreported
bearingREAL (nullable)Degrees, [0, 360); NULL when unreported
altitudeREAL (nullable)Metres above WGS-84 ellipsoid; NULL when unreported

The column names (ts, lat, lng) are internal storage names, not the public API. The Location type exposes timestamp, latitude and longitude. An index on ts ASC serves range queries.

PlatformPath
AndroidApp-private data (Room default), in the app’s own process
iOSLibrary/Application Support/beekon/beekon.db, isExcludedFromBackup = true

On iOS the database is excluded from iCloud backup.

A prune runs every 200 inserts, with two limits:

Age: 7 days (only when sync is off)
Cap: 100,000 rows (always)

The cap keeps the newest 100,000 rows in every mode. The 7-day limit applies only in local-only mode. With sync on, the whole backlog is kept (up to the cap), so a device that was offline for a long time can upload it all when it reconnects.

getLocations(from, to) returns locations within both bounds (inclusive), sorted by timestamp, oldest first.

val now = Instant.now()
val hourAgo = now.minus(1, ChronoUnit.HOURS)
val history: List<Location> = Beekon.getLocations(from = hourAgo, to = now)
// suspend; throws BeekonException.StorageException on DB failure

Reads and writes share one database in WAL mode, so readers don’t block the writer. Reading history while tracking does not delay new locations.

deleteLocations(before) deletes stored locations and returns how many it deleted. Pass a cutoff to delete every location captured strictly before that instant; a location captured exactly at the cutoff is kept. Pass nothing (or nil) to delete them all, which is the on-device half of a “delete my data” request.

val removed: Int = Beekon.deleteLocations(
before = Instant.now().minus(30, ChronoUnit.DAYS),
)
Beekon.deleteLocations() // delete all (before defaults to null)
// suspend; throws BeekonException.StorageException on DB failure

Retention already removes old locations, so use deleteLocations() for erasure on request, not routine cleanup. With sync on, deleting a location that hasn’t been uploaded loses it for good: it never reaches your server.

To label each location with the device’s physical activity, see Activity detection.