Location¶

export interface 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¶

{
   "timestamp":     [Date],     // <-- Javascript Date instance
   "event":         [String],   // <-- motionchange|geofence|heartbeat
   "is_moving":     [Boolean],  // <-- The motion-state when location was recorded.
   "uuid":          [String],   // <-- Universally unique identifier
   "age":           [Integer],  // <-- Age of the location in milliseconds
   "coords": {
       "latitude":  [Double],
       "longitude": [Double],
       "accuracy":  [Double],
       "speed":     [Double],
       "heading":   [Double],
       "altitude":  [Double]
       "ellipsoidal_altitude":  [Double]
   },
   "activity": {
       "type": [still|on_foot|walking|running|in_vehicle|on_bicycle],
       "confidence": [0-100%]
   },
   "battery": {
       "level": [Double],
       "is_charging": [Boolean]
   },
   "odometer": [Double/meters]
}

HTTP POST schema¶

{
    "location": {
        "coords": {
            "latitude":   [Double],
            "longitude":  [Double],
            "accuracy":   [Double],
            "speed":      [Double],
            "heading":    [Double],
            "altitude":   [Double],
            "ellipsoidal_altitude": [Double]
        },
        "extras": {   // <-- optional meta-data
            "foo": "bar"
        },
        "activity": {
            "type": [still|on_foot|walking|running|in_vehicle|on_bicycle|unknown],
            "confidence": [0-100%]
        },
        "geofence": {  // <-- Present only if a geofence was triggered at this location
            "identifier": [String],
            "action": [String ENTER|EXIT]
        },
        "battery": {
            "level": [Double],
            "is_charging": [Boolean]
        },
        "timestamp": [ISO-8601 UTC], // eg:  "2015-05-05T04:31:54.123Z"
        "age":       [Integer],      // <-- Age of the location in milliseconds
        "uuid":      [String],       // <-- Universally unique identifier
        "event"      [String],       // <-- motionchange|geofence|heartbeat
        "is_moving": [Boolean],      // <-- The motion-state when recorded.
        "odometer": [Double/meters]
    }
 }

Members¶

activity¶

activity:MotionActivity;

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

age¶

age: number;

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¶

battery:Battery;

Device battery state at the time this location was recorded.

coords¶

coords:Coords;

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

event¶

event?: string;

SDK event that triggered this location record.

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

extras¶

extras?: Record<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¶

geofence?:GeofenceEvent;

The geofence event that triggered this location, if applicable.

Present only when event is "geofence".

is_moving¶

is_moving: boolean;

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

mock¶

mock?: boolean;

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

odometer¶

odometer: number;

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) => {
  console.log("Distance traveled:", location.odometer);
});

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

odometer_error¶

odometer_error: number;

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

BackgroundGeolocation.onLocation((location) => {
  console.log("Odometer:", location.odometer);
  if (location.odometer_error > 50) {
    console.warn("High odometer drift — signal quality degraded");
  }
});

provider¶

provider?:ProviderChangeEvent;

Location-services provider state at the time this location was recorded.

Present only when event is "providerchange".

sample¶

sample?: boolean;

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¶

timestamp: string;

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

uuid¶

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.