LocationEvent¶
public structLocationEvent
A location record captured by the device's native location API and delivered by the SDK.
iOS uses CLLocationManager / CLLocation; Android uses
FusedLocationProviderClient / android.location.Location.
Contents¶
Overview¶
| Field | Description |
|---|---|
timestamp |
ISO-8601 UTC timestamp from the native API. |
uuid |
Universally unique identifier for this record. |
coords |
Latitude, longitude, accuracy, speed, heading, altitude. |
activity |
Motion activity at time of recording. |
battery |
Battery level and charging state. |
odometer |
Accumulated distance traveled in meters. |
event |
SDK event that triggered this location. |
is_moving |
true when recorded in the moving state. |
sample |
true for intermediate accuracy-sampling locations. |
extras |
Optional custom metadata. |
JavaScript schema¶
// LocationEvent properties:
// location.timestamp // Date?
// location.isMoving // Bool
// location.odometer // Double?
// location.coords?.latitude // Double
// location.coords?.longitude // Double
// location.coords?.accuracy // Double?
// location.coords?.speed // Double?
// location.coords?.heading // Double?
// location.coords?.altitude // Double?
// location.coords?.ellipsoidalAltitude // Double?
// location.activity?.type // String? (still|on_foot|walking|running|in_vehicle|on_bicycle)
// location.activity?.confidence // Int? (0-100)
// location.battery?.level // Double?
// location.battery?.isCharging // Bool?
HTTP POST schema¶
// HTTP POST schema — the JSON body posted to your server:
// {
// "location": {
// "coords": {
// "latitude": Double,
// "longitude": Double,
// "accuracy": Double,
// "speed": Double,
// "heading": Double,
// "altitude": Double,
// "ellipsoidal_altitude": Double
// },
// "extras": { ... },
// "activity": { "type": String, "confidence": Int },
// "geofence": { "identifier": String, "action": String, "timestamp": String },
// "battery": { "level": Double, "is_charging": Bool },
// "timestamp": String, // ISO-8601 UTC
// "uuid": String,
// "event": String, // motionchange|geofence|heartbeat
// "is_moving": Bool,
// "odometer": Double // meters
// }
// }
Members¶
activity¶
public let activity:Activity?
Motion activity detected by the device at the time this location was
recorded (e.g. still, on_foot, in_vehicle).
age¶
Age of the location in seconds, with millisecond precision (e.g. 1.234): how long
before the SDK received the location the native API had fixed it.
recorded_at is the time the SDK received the location, so recorded_at is
roughly timestamp plus age seconds. CurrentPositionRequest.maximumAge, by
contrast, is in milliseconds.
In the Swift API, LocationEvent.age is an Int of whole seconds, rounded down; read
data["age"] for the fractional value.
Warning
Before version 5, age was an integer number of milliseconds. If your code compares it
against a millisecond value, divide that value by 1000.
battery¶
public let battery:Battery?
Device battery state at the time this location was recorded.
coords¶
public let coords:Coords?
Geographic coordinates: latitude, longitude, accuracy, speed, heading, and altitude.
event¶
SDK event that triggered this location record.
One of: "motionchange", "providerchange", "geofence", "heartbeat".
extras¶
Optional arbitrary metadata attached to this location.
Merged with configured PersistenceConfig.extras before persisting and included in the payload posted to HttpConfig.url.
geofence¶
public let geofence:GeofenceTrigger?
The geofence event that triggered this location, if applicable.
Present only when event is "geofence".
isMoving¶
true when the SDK was in the moving state when this location was
recorded.
mock¶
true when the location was generated by a mock location app or simulator.
odometer¶
Accumulated distance traveled in meters since the last odometer reset.
The SDK integrates the distance between each pair of accepted locations to maintain a running total. This value survives app restarts unless explicitly reset.
How it's calculated¶
- Every location the tracking filter accepts goes through the odometer's
position filter, which follows the fixes as closely as their own speed
warrants (
kalmanProfile), and the odometer adds the distance between the positions it last added to. - A location whose accuracy is worse than LocationFilterConfig.odometerAccuracyThreshold is refused and moves nothing.
- Across a gap in the fixes (a tunnel, a garage, an app restart) the odometer adds the straight-line distance between the last position it added to and the first fix after the gap.
- The odometer's uncertainty is exposed via LocationEvent.odometer_error.
When it increases¶
- After the device moves and a new location is recorded.
- While the device is stationary, only when its fixes move beyond the hold radius their accuracy sets.
When it does not increase¶
- When a sample fails accuracy thresholds.
- While the device is stationary and its fixes wander within their accuracy.
- In geofences-only mode, and under
useSignificantChangesOnly: the odometer runs only while location tracking is on.
See also - LocationFilterConfig - LocationFilterConfig.odometerAccuracyThreshold - BGGeo.resetOdometer - BGGeo.getOdometer
let bgGeo = BGGeo.shared
let sub = bgGeo.onLocation { location in
print("Distance traveled:", location.odometer)
}
// Reset at start of a trip
Task {
do {
try await bgGeo.setOdometer(0)
} catch {
print("[setOdometer] error: \(error)")
}
}
odometerError¶
An index of the odometer's uncertainty, in meters.
It grows with the accuracy the device reports, where the path turns, and
where the odometer adds the distance across a gap such as a tunnel, and it
resets with setOdometer and resetOdometer. It is not a confidence interval
and states no probability. It does not include systematic error, such as the
distance a straight chord misses on a curved road.
Compare values from one device over time rather than across devices: a device that reports coarser accuracy produces a larger index on the same road.
See also
- odometer
let bgGeo = BGGeo.shared
let sub = bgGeo.onLocation { location in
print("Odometer:", location.odometer)
// Note: odometer_error may be available via location.data dictionary
}
recordedAt¶
Timestamp when the SDK received the location from the native API.
- When PersistenceConfig.timestampFormat is
"iso"(default): ISO-8601 UTCstring. - When PersistenceConfig.timestampFormat is
"epoch": epoch millisecondsnumber.
In the Swift API, recordedAt is a Date, and recordedAtString carries the string. In the Kotlin
API it is the String described above.
sample¶
true for intermediate sample locations collected during accuracy
convergence.
The SDK collects multiple samples when transitioning between motion states or during BGGeo.getCurrentPosition to find the most accurate fix. These samples are delivered to BGGeo.onLocation but are not persisted to SQLite. Filter them out before manually posting locations to your server.
timestamp¶
Timestamp provided by the native location API.
- When PersistenceConfig.timestampFormat is
"iso"(default): ISO-8601 UTCstring(eg"2025-04-10T12:00:01.123Z"). - When PersistenceConfig.timestampFormat is
"epoch": epoch millisecondsnumber.
In the Swift API, timestamp is a Date, and timestampString carries the string. In the Kotlin
API it is the String described above.
uuid¶
Universally unique identifier for this location record.
Use this to correlate locations in your server database with those in the SDK logs, or to detect whether a location has been delivered more than once.