Skip to content

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
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":           [Double],   // <-- Age of the location in seconds
   "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],
            "timestamp": [ISO-8601 UTC]
        },
        "battery": {
            "level": [Double],
            "is_charging": [Boolean]
        },
        "timestamp": [ISO-8601 UTC], // eg:  "2015-05-05T04:31:54.123Z"
        "age":       [Double],       // <-- Age of the location in seconds
        "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 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

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?:GeofenceTrigger;

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
  • 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 LocationFilter.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 Location.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 - LocationFilter - LocationFilter.odometerAccuracyThreshold - BackgroundGeolocation.resetOdometer - BackgroundGeolocation.getOdometer

BackgroundGeolocation.onLocation((location) => {
  console.log("Distance traveled:", location.odometer);
});

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

odometer_error

odometer_error: number;

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

BackgroundGeolocation.onLocation((location) => {
  console.log("Odometer:", location.odometer);
  if (location.odometer_error > 50) {
    console.warn("Odometer uncertainty is high");
  }
});

provider

provider?:ProviderChangeEvent;

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

Present only when event is "providerchange".

recorded_at

recorded_at: string | number;

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

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 | number;

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

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.