Interface LocationFilter

Defines the filtering policy applied to incoming raw GPS samples before they are accepted, averaged, or rejected by the LocationFilter.

The filtering policy determines how aggressively the plugin removes noisy, inaccurate, or redundant location updates. It represents the first stage in the SDK’s data-quality pipeline — before Kalman smoothing, burst averaging, or other denoising steps are applied.

Choosing the correct policy depends on your app’s tolerance for jitter versus responsiveness:

• Fitness or vehicle-tracking apps often prefer stronger filtering.
• Survey or scientific apps may prefer capturing unmodified raw samples.

Profiles

Notes

• This policy affects only the SDK’s internal filtering pipeline. It does not modify the raw values returned to BackgroundGeolocation.onLocation.
• For more granular tuning, see LocationFilter.trackingAccuracyThreshold, LocationFilter.maxImpliedSpeed, and other LocationFilter fields.

Examples

Balanced default filtering:

BackgroundGeolocation.ready({
  geolocation: {
    filter: {
      policy: LocationFilterPolicy.Adjust
    }
  }
});
Copy

No filtering — capture all raw locations:

BackgroundGeolocation.ready({
  geolocation: {
    filter: {
      policy: LocationFilterPolicy.PassThrough
    }
  }
});
Copy

Maximum smoothing for analytics:

BackgroundGeolocation.ready({
  geolocation: {
    filter: {
      policy: LocationFilterPolicy.Conservative
    }
  }
});
Copy

See also

• GeoConfig.filter
• LocationFilter
• KalmanProfile

Enables the Kalman filter to smooth incoming location speed and position.

When true, the SDK applies a Kalman filter to reduce noise and stabilize velocity and distance calculations. Defaults to true.

Enables verbose Kalman debug output in logs.

When true, the SDK logs additional diagnostic data about the Kalman filter’s internal state (for example, variance and innovation) for each incoming sample.

Specifies the preset tuning profile for the Kalman filter used in location denoising.

Each profile adjusts the Kalman filter’s process and measurement noise parameters, trading off between responsiveness and smoothness:

• If no profile is provided, defaultProfile is applied.
• Use aggressive for fast-changing activities requiring rapid updates.
• Use conservative when stability and track smoothness are more important than immediate responsiveness.

This maps directly to native Kalman tuning implementations on both Android and iOS.

Number of samples in the rolling window used for burst averaging.

Higher values produce smoother averaged locations but introduce greater latency in responsiveness to movement.

Default: 5.

Duration (in seconds) of each burst window used for averaging samples.

The plugin groups all locations received within this time window into a single averaged output sample.

Default: 10 seconds.

Maximum distance (in meters) between samples considered part of the same burst.

Prevents the filter from merging location samples that are too far apart into a single averaged point.

Default: 300 meters.

Minimum acceptable horizontal accuracy (in meters) for a sample to qualify for tracking.

Locations with an accuracy value greater (worse) than this threshold are discarded and will not be used in path or odometer calculations.

Default: 100 meters.

Maximum implied speed (in meters/second) permitted before a location sample is rejected.

If a raw sample implies a speed greater than this threshold, it is considered an unrealistic outlier and will be discarded by the filter.

Default: 60 m/s (≈ 216 km/h).

Enables verbose debug logging for the filtering engine.

When true, the SDK logs detailed decisions for each incoming sample, including whether it was ACCEPTED, REJECTED, or IGNORED by the filtering pipeline.

Applies a Kalman filter only to odometer calculations, independent of LocationFilter.useKalman.

When true, the odometer’s internal distance-accumulation logic applies a Kalman filter to smooth incoming samples, reducing jitter and noise without modifying the recorded track points.

This is useful when you want smoother odometer readings while preserving the raw location stream for mapping, analysis, or debugging.

If both LocationFilter.useKalman and LocationFilter.odometerUseKalmanFilter are true, the SDK maintains independent Kalman filter instances for tracking and odometer calculations.

Default: true.

Maximum horizontal accuracy (in meters) allowed for a sample to affect the odometer.

Any location whose accuracy exceeds this threshold is ignored for odometer updates.

Default: 20.