Location¶

class Location

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¶

// Location object properties:
// location.timestamp         // String (ISO-8601 UTC)
// location.uuid              // String
// location.isMoving          // bool
// location.event             // String (motionchange|geofence|heartbeat)
// location.age               // double (milliseconds)
// 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 // bool
// location.extras            // Map? (optional custom metadata)

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¶

Activityactivity

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

BackgroundGeolocation.onLocation((Location location) {
  activityType = location.activity.type;
  int confidence = location.activity.confidence;

  print("[onLocation] Motion activity, type: $activityType, confidence: $confidence");
});

age¶

double age

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¶

Batterybattery

Device battery state at the time this location was recorded.

BackgroundGeolocation.onLocation((Location location) {
  bool isCharging = location.battery.isCharging;
  double level    = location.battery.level;

  print("[onLocation] Battery state, isCharging: $isCharging, level: $level");
});

coords¶

Coordscoords

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

BackgroundGeolocation.onLocation((Location location) {
  double accuracy = location.coords.accuracy;
  double lat      = location.coords.latitude;
  double lng      = location.coords.longitude;
  double speed    = location.coords.speed;
  double heading  = location.coords.heading;
  double altitude = location.coords.altitude;

  print("[onLocation] $location");
});

event¶

String event

SDK event that triggered this location record.

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

extras¶

Map? 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¶

GeofenceEvent? geofence

The geofence event that triggered this location, if applicable.

Present only when event is "geofence".

is_moving¶

bool isMoving

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

mock¶

bool mock

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

odometer¶

double 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¶

Distance is computed between each consecutive pair of accepted locations.
The LocationFilter evaluates accuracy and motion context for each sample. Low-quality samples may be rejected or down-weighted based on LocationFilter.odometerAccuracyThreshold.
Accumulated drift is exposed via Location.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.

BackgroundGeolocation.onLocation((Location location) {
  print('Distance traveled: ${location.odometer}');
});

// Reset at the start of a trip
await BackgroundGeolocation.resetOdometer();

sample¶

bool sample

true for intermediate sample locations collected during accuracy convergence.

The SDK collects multiple samples when transitioning between motion states or during BackgroundGeolocation.getCurrentPosition to find the most accurate fix. These samples are delivered to BackgroundGeolocation.onLocation but are not persisted to SQLite. Filter them out before manually posting locations to your server.

timestamp¶

String recordedAt

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

uuid¶

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