Data types

Every type is a Kotlin data class decoded from the engine’s JSON. Fields that the engine may legitimately omit are nullable; fields it always sends are not. Where a field is nullable, that nullability is load-bearing — see the note on isMoving at the end.

Location

The payload of onLocation, the return of getCurrentPosition(), and the record shape in the upload queue.

Field	Type	Notes
`uuid`	`String`	Stable per record; the handle `destroyLocation()` takes.
`timestamp`	`String`	ISO 8601, UTC.
`age`	`Double?`	Milliseconds between the fix being taken and processed.
`odometer`	`Double`	Cumulative metres since the last reset.
`coords`	`Coords`	See below.
`activity`	`MotionActivity`	Classification at the time of the fix.
`battery`	`Battery`	Level and charging state.
`isMoving`	`Boolean`	The motion machine’s verdict for this fix.
`sample`	`Boolean?`	`true` for a `getCurrentPosition()` sample that was not persisted.
`event`	`String?`	`"motionchange"`, `"heartbeat"`, `"geofence"`, or absent for an ordinary fix.
`extras`	`JSONObject?`	Whatever you attached via config or `getCurrentPosition(extras = …)`.

Coords

Field	Type	Notes
`latitude`	`Double`
`longitude`	`Double`
`accuracy`	`Double`	Horizontal radius, metres — the number the accuracy gate filters on.
`altitude`	`Double?`	Metres above sea level.
`altitudeAccuracy`	`Double?`
`speed`	`Double?`	m/s. `-1` means “unknown” on some devices; treat negatives as absent.
`speedAccuracy`	`Double?`
`heading`	`Double?`	Degrees; negative means unknown.
`headingAccuracy`	`Double?`
`ellipsoidalAltitude`	`Double?`	Height above the WGS84 ellipsoid, where the device reports it.

MotionActivity

Field	Type	Notes
`type`	`ActivityType`	`STILL`, `WALKING`, `IN_VEHICLE`, …
`confidence`	`Int`	0–100, from Play Services activity recognition.

The engine ignores a classification below minimumActivityRecognitionConfidence (75 by default) when deciding motion state, so a low-confidence IN_VEHICLE does not by itself wake tracking.

Battery

Field	Type	Notes
`level`	`Double`	0.0–1.0. `-1` means unknown — guard before showing a percentage.
`isCharging`	`Boolean`

State

Returned by ready(), setConfig(), start(), stop() and getState().

Field	Type	Notes
`enabled`	`Boolean`	Whether tracking is on. This is the persisted intent, not “is a fix arriving right now”.
`raw`	`JSONObject`	Everything else the engine reported.

raw is deliberately untyped: it is a superset of health and diagnostic fields that grows with the engine, and a typed class would have to be released in lockstep to stay honest. Read it with state["key"], which returns null for both an absent key and a JSON null:

val state = BackgroundGeolocation.getState()
val trackingActive = state["trackingActive"] as? Boolean
val lastFixAge = state["lastAcceptedFixAge"] as? Double   // seconds, null until a fix arrives

Fields the Android engine reports today: enabled, trackingMode, isMoving, odometer, geofenceCount, lastGeofenceError, connected, trackingActive, authorization, lastRawFixAge, lastAcceptedFixAge. The two fix ages are in seconds and are null until the first fix — the raw one is stamped before the location filter runs and the accepted one after, so the pair tells “the OS stopped delivering fixes” apart from “the filter is rejecting them”.

ProviderState

From getProviderState(), and the payload of onProviderChange.

Field	Type	Notes
`status`	`AuthorizationStatus`	The grant.
`enabled`	`Boolean`	Location services on at all.
`gps`	`Boolean`	GPS provider enabled.
`network`	`Boolean`	Network provider enabled.
`accuracyAuthorization`	`AccuracyAuthorization?`	`REDUCED` when the user granted approximate location only.

Geofence

Field	Type	Notes
`identifier`	`String`	Yours; unique. Re-adding the same identifier replaces the fence.
`radius`	`Double`	Metres. Under ~100 m, expect the OS to report crossings late.
`latitude` / `longitude`	`Double`
`notifyOnEntry`	`Boolean?`	Defaults to true engine-side.
`notifyOnExit`	`Boolean?`	Defaults to true engine-side.
`notifyOnDwell`	`Boolean?`	Requires `loiteringDelay`.
`loiteringDelay`	`Double?`	Milliseconds inside the radius before DWELL fires.
`extras`	`JSONObject?`	Echoed back on every event for this fence.

Event payloads

MotionChangeEvent

Field	Type	Notes
`isMoving`	`Boolean`
`location`	`Location?`	Null on the first motionchange of a tracking session on Android — the engine has no accepted fix yet.

GeofenceEvent

Field	Type	Notes
`identifier`	`String`
`action`	`GeofenceAction`	`ENTER`, `EXIT`, `DWELL`.
`location`	`Location`	The last accepted fix when the OS delivered the transition — not the point where the boundary was crossed.
`extras`	`JSONObject?`	From the geofence definition.

GeofencesChangeEvent

Field	Type	Notes
`on`	`List<Geofence>`	Now being monitored by the OS.
`off`	`List<Geofence>`	No longer monitored.

Android limits how many regions one app can monitor, so the engine keeps the nearest maxMonitoredGeofences armed and swaps as you move. This event is how you see that happen; the fences you added all still exist.

HttpEvent

Field	Type	Notes
`success`	`Boolean`	2xx.
`status`	`Int`	HTTP status; `0` means a network-level failure, not a server response.
`responseText`	`String`	Body, truncated to 1024 chars. Logged verbatim — do not put secrets in error bodies.

ConnectivityChangeEvent

Field	Type
`connected`	`Boolean`

Validated connectivity, not merely “an interface is up” — a captive portal reads as disconnected.

HeartbeatEvent

Field	Type
`raw`	`JSONObject`

Option classes

CurrentPositionOptions

Field	Type	Notes
`persist`	`Boolean?`	Whether the fix enters the upload queue.
`samples`	`Int?`	How many fixes to collect before returning the best.
`timeout`	`Double?`	Seconds.
`maximumAge`	`Double?`	Milliseconds; accept a cached fix younger than this.
`desiredAccuracy`	`Int?`	Overrides config for this call.
`extras`	`JSONObject?`	Attached to the returned record.

WatchPositionOptions

Field	Type
`interval`	`Double?`
`desiredAccuracy`	`Int?`
`persist`	`Boolean?`
`extras`	`JSONObject?`

AuthState

Field	Type
`accessToken`	`String?`
`refreshToken`	`String?`

The engine’s current token pair after a native refresh — read it with getAuthState() when your app needs to stay in step with tokens the SDK rotated on its own. See HTTP & authorization.

LogEntry

Field	Type	Notes
`ts`	`String`	ISO 8601.
`level`	`Int`	1=ERROR … 5=VERBOSE.
`src`	`String`	`"native"` for engine lines.
`event`	`String`	Dot-namespaced (`track.start`, `wake.rearm`) for engine diagnostics.
`message`	`String?`
`data`	`Any?`	Parsed JSON, not a string.

A note on nullability

Nullable fields here are not defensive padding. MotionChangeEvent.location really is absent on the first motion change of a session, and Location.isMoving arrives as null from the engine while motion is still being probed — up to stopTimeout minutes after start(). An earlier SDK declared that field non-null on the strength of a TypeScript interface, and dropped every location for the first minutes of every session while the server received them all. If a field is nullable in this table, the engine can and does send nothing for it.