Skip to content

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

public let age: Int?

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

public let event: String?

SDK event that triggered this location record.

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

extras

public let extras: [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

public let geofence:GeofenceTrigger?

The geofence event that triggered this location, if applicable.

Present only when event is "geofence".

isMoving

public let isMoving: Bool

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

mock

public let mock: Bool?

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

odometer

public let 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

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

public let 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

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

public let recordedAt: Date?

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.

sample

public let sample: Bool

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

public let timestamp: Date?

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.

uuid

public let 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.