Adaptive Distance Filter

The auto distance filter adjusts the minimum distance between location updates based on the device's current speed. Slower movement produces smaller filters (more precision), faster movement produces larger filters (less battery drain).

How It Works

When distanceFilter: 'auto' is set, the plugin calculates the distance filter dynamically from each received location's speed value. The goal is to maintain a consistent time interval between updates (configured by targetInterval).

Low speed (walking): Filter shrinks to minDistance — frequent, precise updates.
Moderate speed (cycling): Filter grows proportionally — balanced updates.
High speed (driving): Filter grows to maxDistance — fewer updates, less battery.
Stationary: Filter stays at minDistance, heartbeats fire normally.

The current effective filter is returned in the effectiveDistanceFilter field of each Location object.

Configuration

interface AutoDistanceFilterConfig {
  targetInterval?: number;  // seconds between updates (default: 10)
  minDistance?: number;      // minimum filter in meters (default: 10)
  maxDistance?: number;      // maximum filter in meters (default: 500)
}

await configure({
  distanceFilter: 'auto',
  autoDistanceFilter: {
    targetInterval: 10,   // aim for ~10 seconds between updates
    minDistance: 10,       // never go below 10 meters
    maxDistance: 500,      // never exceed 500 meters
  },
});

Recommended Settings by Use Case

Use Case	targetInterval (s)	minDistance (m)	maxDistance (m)	Notes
Walking / Hiking	8–12	5–10	100–200	Frequent updates at low speed, caps filter for paused movement.
Cycling	8–10	10–15	300	Balanced for moderate speeds, smooth polyline.
Driving / Fleet	10–15	10–20	500–1000	Larger max for highway speeds, reduces battery drain.
Delivery / Mixed	10	10	500	Default values work well for mixed walking + driving.

When to Use Auto vs Fixed

Use Auto When

Users switch between transport modes
Battery optimization is a priority
Time-based update intervals are preferred over distance-based
Fleet / delivery tracking with mixed driving and walking

Use Fixed When

Consistent precision is needed regardless of speed
The app targets a single transport mode
You need exact distance-based granularity (e.g., every 10m)
Fitness tracking where polyline accuracy matters most

Check Active Mode

The ConfigureResult includes distanceFilterMode: 'auto' | 'fixed' so you can confirm which mode is active after calling configure().