Interface Location

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

The age of the location in milliseconds, relative to the Device system-time when the location was received. For example, if the reported age is 10000, that location was recorded 10s ago, relative to the system-time. location.timestamp + location.age = Device system-time when location was recorded.

Total distance traveled, in meters, since the odometer was last set or reset.

The SDK continuously integrates distance between recorded locations to maintain a running total. This value increases regardless of tracking mode and persists across app restarts (unless explicitly reset).

ℹ️ How it's calculated:

• Distance is computed between each pair of accepted locations.
• The LocationFilter evaluates the accuracy and motion context of each sample.
• Low-quality samples may be rejected or down-weighted depending on LocationFilter.odometerAccuracyThreshold, reducing odometer pollution.
• The accumulated drift is exposed via Location.odometer_error.

When the odometer increases:

• After the device moves and a new location is recorded.
• During both moving and stationary states (if minor motion is detected).
• In geofences-only mode, the odometer increases whenever a location is recorded for a geofence transition or stationary exit.

When it does not increase:

• When a sample fails accuracy thresholds.
• When is_moving is false and no sufficient movement occurs.

Resetting or setting the odometer:

• Use BackgroundGeolocation.resetOdometer to zero it out.
• Use BackgroundGeolocation.setOdometer to force a new value manually. This also resets Location.odometer_error to 0.

Persistence:

• The odometer value is stored in State and is restored after app restart.
• Only a user-initiated reset or explicit call to setOdometer clears it.

Best practices:

• Display the odometer directly to users (e.g., trip distance, workout distance).
• Use Location.odometer_error to measure confidence in the odometer.
• For fitness apps, consider resetting it at the beginning of each workout session.

Accumulated odometer drift, in meters.

ℹ️ Why does this exist?

• The SDK maintains a continuously increasing odometer value by integrating distance between recorded locations.
• When GNSS accuracy is degraded (tunnels, downtown canyons, indoor / underground environments), distance calculations can accumulate drift.
• The odometer_error value tells you how much uncertainty has accumulated in the current odometer estimate.

How to use it:

• Treat this as a “confidence interval” for odometer.
  For example, if odometer = 12000 and odometer_error = 40, the true travelled 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 (e.g., < 10m) during good GPS conditions, but can grow during:
  • long tunnels
  • heavy multipath environments
  • extended indoor tracking

Best practice:

• Display odometer normally to end-users.
• Use odometer_error internally for data-quality scoring, filtering, or highlighting low-accuracy segments.

true if location was recorded while plugin is in the moving state.

Universally Unique Identifier. You can use this to match locations recorded at your server with those in the logs. It can also be used to ensure if the plugin has ever posted the same location twice.

Event responsible for generating this location (motionchange, providerchange, geofence, heartbeat).

Present (and true) if the location was generated by a "Fake Location" application or simulator.

true if the plugin is currently waiting for the best possible location to arrive. Samples are recorded when the plugin is transitioning between motion-states (moving vs stationary) or [[BackgroundGeolocation.getCurrentPosition]]. If you're manually posting location to your server, you should not persist these "samples".

latitude, longitude, speed, heading, etc.

Device battery level when the location was recorded.

Optional arbitrary meta-data attached to this location.

If this location was recorded due to a geofence transition, the corresponding geofence-event.

Device motion-activity when this location was recorded (eg: still, on_foot, in_vehicle).

If this location was recorded due to ProviderChangeEvent, this is a reference to the location-provider state.