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
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        // 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 },
//     "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 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.

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¶

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.

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?

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

let bgGeo = BGGeo.shared

let sub = bgGeo.onLocation { location in
    print("Odometer:", location.odometer)
    // Note: odometer_error may be available via location.data dictionary
}

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?

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

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.