LocationFilter¶

export interface LocationFilter {

Filters, denoises, and smooths raw GPS samples before they are recorded or used for odometer calculations.

LocationFilter is supplied via GeoConfig.filter and provides fine-grained control over how the SDK handles noisy or inconsistent location data from the underlying platform.

Contents¶

Overview
Examples

Overview¶

The SDK applies several processing stages to each raw GPS sample before recording it: Kalman filtering, rolling-window burst averaging, and speed/distance/accuracy constraints. These produce smoother paths, reduce jitter, and improve odometer stability.

Field	Description
`policy`	Selects which filtering policy to apply. See LocationFilterPolicy.
`useKalman`	Enables Kalman filtering of speed and position (default: `true`).
`kalmanDebug`	Enables verbose Kalman diagnostic logs (default: `false`).
`kalmanProfile`	Selects a Kalman tuning profile (see KalmanProfile).
`rollingWindow`	Number of samples for rolling burst averaging. Larger values increase smoothness but reduce responsiveness. Default: `5`.
`burstWindow`	Duration of each averaging burst (seconds). Default: `10`.
`maxBurstDistance`	Maximum distance (meters) for samples included in the same burst window. Default: `300`.
`trackingAccuracyThreshold`	Maximum GPS horizontal accuracy (meters) required to accept a location. Default: `100`.
`maxImpliedSpeed`	Maximum implied speed (m/s) before rejecting a sample as unrealistic. Default: `60` (≈ 216 km/h).
`filterDebug`	Enables verbose logging of filter decisions (default: `false`).
`odometerUseKalmanFilter`	Applies Kalman smoothing to odometer calculations (default: `true`).
`odometerAccuracyThreshold`	Maximum accuracy (meters) allowed for a sample to affect the odometer. Default: `20`.

Distances are in meters.
Time fields are in seconds unless noted otherwise.
Filtering affects recorded locations only — it does not influence real-time motion detection.

BackgroundGeolocation.ready({
  geolocation: {
    filter: {
      policy: LocationFilterPolicy.Adjust,
      useKalman: true,
      kalmanProfile: KalmanProfile.Default,
      trackingAccuracyThreshold: 100,
      odometerAccuracyThreshold: 20
    }
  }
});

Examples¶

BackgroundGeolocation.ready({
  geolocation: {
    filter: {
      policy: LocationFilterPolicy.PassThrough,
      useKalman: false
    }
  }
});

Members¶

burstWindow¶

burstWindow?: number;

Duration in seconds of each burst window used for averaging samples. Defaults to 10 seconds. Valid range: 0.2–120.

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

filterDebug¶

filterDebug?: boolean;

Enables verbose debug logging for the filtering engine. Defaults to false.

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

kalmanDebug¶

kalmanDebug?: boolean;

Enables verbose Kalman debug output in logs. Defaults to false.

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

kalmanProfile¶

kalmanProfile?:KalmanProfile;

Selects the preset tuning profile for the Kalman filter. Defaults to KalmanProfile.Default.

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

Profile	Behaviour
`defaultProfile`	Balanced — General-purpose; suitable for most movement types.
`aggressive`	Aggressive — Fast response; minimal smoothing.
`conservative`	Conservative — Maximum smoothing; slowest response to changes.

Use aggressive for fast-changing activities requiring rapid updates. Use conservative when stability and track smoothness are more important than immediate responsiveness.

maxBurstDistance¶

maxBurstDistance?: number;

Maximum distance in meters between samples considered part of the same burst. Defaults to 300 meters. Valid range: 5–2000.

Prevents the filter from merging location samples that are too far apart into a single averaged point. Works alongside maxImpliedSpeed — whichever flags a sample first applies.

maxImpliedSpeed¶

maxImpliedSpeed?: number;

Maximum implied speed in meters/second permitted before a location sample is rejected. Defaults to 60 m/s (≈ 216 km/h). Valid range: 1–200.

If a raw sample implies a speed greater than this threshold — calculated as distance divided by elapsed time between samples — it is treated as an unrealistic outlier and discarded by the filter.

odometerAccuracyThreshold¶

odometerAccuracyThreshold?: number;

Maximum horizontal accuracy in meters allowed for a sample to affect the odometer. Defaults to 20 meters. Valid range: 0–500.

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

odometerUseKalmanFilter¶

odometerUseKalmanFilter?: boolean;

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

When enabled, 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 smoother odometer readings are needed 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.

policy¶

policy?:LocationFilterPolicy;

Selects the filtering policy applied to incoming raw GPS samples before they are accepted, averaged, or rejected. Defaults to LocationFilterPolicy.Conservative.

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

Policy	Description	Use case
LocationFilterPolicy.PassThrough	No filtering. Every received sample is recorded, even if noisy or identical to the previous one.	Debugging, diagnostics, scenarios requiring raw data.
LocationFilterPolicy.Adjust	Balanced filtering. Smooths and caps only clearly invalid samples.	Most use cases — walking, cycling, automotive tracking.
LocationFilterPolicy.Conservative	Strict filtering. Strongly smooths data and rejects high-variance samples, prioritizing stability over responsiveness. (Default)	Analytics, long-term background logging, noise-sensitive applications.

Choosing the correct policy depends on your app's tolerance for jitter versus responsiveness: - Fitness or vehicle-tracking apps often prefer Adjust for lower latency. - Survey or analytics apps may prefer Conservative for maximum stability, or PassThrough to capture unmodified raw samples.

Note

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.

See also - GeoConfig.filter - LocationFilter - KalmanProfile

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

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

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

Balanced default filtering¶

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

No filtering — capture all raw locations:¶

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

Maximum smoothing for analytics:¶

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

rollingWindow¶

rollingWindow?: number;

Number of samples in the rolling window used for burst averaging. Defaults to 5. Valid range: 3–20.

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

trackingAccuracyThreshold¶

trackingAccuracyThreshold?: number;

Maximum acceptable horizontal accuracy in meters for a sample to qualify for tracking. Defaults to 100 meters. Valid range: 0–500.

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

useKalman¶

useKalman?: boolean;

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

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