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
JavaScript schema
HTTP POST schema

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 },
//     "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 milliseconds, measured from the device system clock at the time the location was received.

location.timestamp + location.age = device system time when the SDK received the location from the native API.

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¶

Distance is computed between each consecutive pair of accepted locations.
The LocationFilterConfig evaluates accuracy and motion context for each sample. Low-quality samples may be rejected or down-weighted based on LocationFilterConfig.odometerAccuracyThreshold.
Accumulated drift is exposed via LocationEvent.odometer_error.

When it increases¶

After the device moves and a new location is recorded.
During both moving and stationary states when minor motion is detected.
In geofences-only mode, at each geofence transition or stationary exit.

When it does not increase¶

When a sample fails accuracy thresholds.
When the device is stationary and no sufficient movement is detected.

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

Accumulated odometer drift in meters.

Represents the uncertainty that has built up in the odometer value due to GPS noise, tunnel blackouts, and other inaccurate samples.

How to use it¶

Treat this as a confidence interval for odometer. For example, if odometer = 12000 and odometer_error = 40, the true traveled distance is likely within ±40 meters of the reported value.

Resetting or setting a new odometer value automatically resets odometer_error to 0. Values typically remain low (< 10 m) under good GPS conditions but grow during long tunnels, dense urban canyons, or extended indoor tracking.

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.
}

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

ISO-8601 UTC timestamp provided by the native location API.

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.