Skip to content

LocationEvent

classLocationEvent

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        // String
// location.isMoving         // Boolean
// location.odometer         // Double (meters)
// 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.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 // Boolean
// location.extras            // JSONObject?

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
//     },
//     "extras": { ... },
//     "activity": { "type": String, "confidence": Int },
//     "geofence": { "identifier": String, "action": String, "timestamp": String },
//     "battery":  { "level": Double, "is_charging": Boolean },
//     "timestamp": String,   // ISO-8601 UTC
//     "uuid":      String,
//     "event":     String,   // motionchange|geofence|heartbeat
//     "is_moving": Boolean,
//     "odometer":  Double    // meters
//   }
// }

Members

accuracy

val accuracy: Float?

Horizontal accuracy radius in meters.

activity

val activity:LocationEvent.Activity?

Motion activity detected by the device at the time this location was recorded (e.g. still, on_foot, in_vehicle).

age

val age: Double?

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.

altitude

val altitude: Double?

Altitude above a reference plane in meters.

iOS

Altitude above mean sea level.

Android

Altitude above the WGS84 reference ellipsoid. See also ellipsoidal_altitude.

altitudeAccuracy

val altitudeAccuracy: Float?

Vertical accuracy in meters. Returns -1 if unavailable.

iOS

When positive, the altitude value is within ±altitude_accuracy meters. When negative, altitude is invalid. Determining altitude accuracy requires a GPS-capable device; on some devices this value is always negative.

Android

Defined as the 1-sigma vertical accuracy at 68% confidence — the half-width of the range above and below altitude within which the true altitude has a 68% probability of falling.

battery

val battery:LocationEvent.Battery?

Device battery state at the time this location was recorded.

confidence

val confidence: Int?

Confidence of the reported activity as a percentage (0–100).

coords

val coords:LocationEvent.Coords?

Geographic coordinates: latitude, longitude, accuracy, speed, heading, and altitude.

event_

val event_: String?

SDK event that triggered this location record.

One of: "motionchange", "providerchange", "geofence", "heartbeat".

extras

val extras: Map<String, Any>?

Optional arbitrary metadata attached to this location.

Merged with configured PersistenceConfig.extras before persisting and included in the payload posted to HttpConfig.url.

geofence

val geofence:LocationEvent.GeofenceTrigger?

The geofence event that triggered this location, if applicable.

Present only when event is "geofence".

heading

val heading: Float?

Direction of travel in degrees (0–360, clockwise from true north).

Note

Only present when the location came from GPS. Returns -1 otherwise.

headingAccuracy

val headingAccuracy: Float?

Heading accuracy in degrees.

Note

Only present when the location came from GPS. Returns -1 otherwise.

isCharging

val isCharging: Boolean?

true when the device is connected to a power source.

isMock

val isMock: Boolean

true when the location was generated by a mock location app or simulator.

isMoving

val isMoving: Boolean

true when the SDK was in the moving state when this location was recorded.

isSample

val isSample: Boolean

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.

latitude

val latitude: Double

Latitude in decimal degrees.

level

val level: Float?

Battery charge level: 0.0 = empty, 1.0 = fully charged.

longitude

val longitude: Double

Longitude in decimal degrees.

odometer

val odometer: Double

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

val bgGeo = BGGeo.instance

bgGeo.onLocation { location ->
    Log.d(TAG, "Distance traveled: ${location.odometer}")
}

// Reset at start of a trip
// Within a coroutine scope
bgGeo.setOdometer(0.0)

odometerError

val odometerError: Double

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

val bgGeo = BGGeo.instance

bgGeo.onLocation { location ->
    Log.d(TAG, "Odometer: ${location.odometer}")
    // Note: odometer_error is not exposed in the Kotlin LocationEvent API.
    // Use location.toJson() to inspect the full JSON payload if needed.
}

recordedAt

val recordedAt: String

Timestamp when the SDK received the location from the native API.

In the Swift API, recordedAt is a Date, and recordedAtString carries the string. In the Kotlin API it is the String described above.

speed

val speed: Float?

Ground speed in meters per second.

Note

Only present when the location came from GPS. Returns -1 otherwise.

speedAccuracy

val speedAccuracy: Float?

Speed accuracy in meters per second.

Note

Only present when the location came from GPS. Returns -1 otherwise.

timestamp

val timestamp: String

Timestamp provided by the native location API.

In the Swift API, timestamp is a Date, and timestampString carries the string. In the Kotlin API it is the String described above.

type

val type: String?

Detected motion activity type (e.g. still, on_foot, in_vehicle).

uuid

val uuid: String?

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.