Conservative GPS Outlier Filtering Parameters in google-timeline-visualizer

Conservative GPS outlier filtering uses four hard-coded heuristics: a maximum run length of 3 points, a 1300 km/h speed ceiling, a 200 meter distance threshold from the window's first point, and a 500 meter proximity check to surrounding valid points. These parameters automatically clean isolated, implausible location spikes from Google Timeline exports.

The google-timeline-visualizer repository by mahlernim provides automated filtering to remove GPS artifacts without discarding legitimate travel data. The conservative mode—enabled by default—applies cautious heuristics designed to catch obvious errors while preserving unusual but real movement patterns.

---

How to Enable Conservative GPS Outlier Filtering

The filter runs automatically when you use the tool without overriding the default setting.

Command-Line Usage

# Default: conservative filtering applied

python visualizer.py --input Timeline.json

# Explicit conservative mode (same as default)

python visualizer.py --input Timeline.json --filter-outliers conservative

# Disable filtering entirely

python visualizer.py --input Timeline.json --filter-outliers off

The --filter-outliers flag accepts two values as defined at line 1029 of visualizer.py: "conservative" (default) or "off".

Python API Usage

from visualizer import filter_location_outliers

# Apply conservative filtering

clean_points, removed = filter_location_outliers(raw_points, mode="conservative")
print(f"Removed {removed} GPS outliers.")

# Disable filtering

clean_points, removed = filter_location_outliers(raw_points, mode="off")

---

Core Parameters for Conservative GPS Outlier Filtering

The filter_location_outliers() function in visualizer.py applies four interlocking heuristics. Each parameter targets a specific failure mode of consumer GPS hardware.

Maximum Run Length: 3 Consecutive Points

Only isolated bursts qualify for removal. The helper _suspicious_run_end (line 18) caps examination windows at three points. Longer sequences are assumed to represent actual movement rather than sensor error.

This prevents the filter from discarding legitimate rapid transit—3 points at typical sampling intervals covers only brief temporal windows.

Speed Ceiling: 1300 km/h

Points requiring travel speeds above 1300 km/h between surrounding valid points trigger immediate flagging. The _speed_km_per_hour calculation (line 301) compares great-circle distance against timestamp deltas.

This threshold exceeds commercial aviation cruise speeds (~900 km/h), catching only physically impossible jumps while sparing legitimate flight data.

Distance from Window Origin: 200 meters

Within each candidate run, points more than 200 meters from the window's first point raise suspicion. The haversine_dist > 200 check (line 305) identifies spatial outliers relative to local context.

This filters single-point "jumps" without affecting gradual drift or actual short-distance movement.

Proximity to Valid Neighbors: 500 meters

The final gate requires candidate points to sit within 500 meters of either the preceding valid point (before) or the subsequent valid point (after). The haversine_dist < 500 test (line 308) implements this.

Points satisfying all four criteria are removed; the function returns the cleaned list and a removal count.

---

Implementation Details in visualizer.py

The filtering logic resides in visualizer.py with these key components:

Component	Location	Purpose
filter_location_outliers(points, mode="conservative")	Main function entry	Orchestrates the filtering pipeline
_suspicious_run_end	Line 18	Identifies candidate point runs (≤3 points)
_speed_km_per_hour	Line 301	Computes implied travel speed
haversine_dist comparisons	Lines 305, 308	Apply distance thresholds

The algorithm proceeds sequentially: locate a short run of points, compute speeds to neighbors, check distance relationships, and conditionally delete. This single-pass design keeps computational overhead minimal for large location histories.

---

Cross-Platform Consistency

The conservative GPS outlier filtering heuristics are replicated across implementations:

• web/src/outlier.ts — TypeScript version serving the web UI
• web/src/outlier.test.ts — JavaScript test suite validating behavior
• tests/test_outlier_filter.py — Python unit tests confirming 3-point run removal

Both implementations use identical threshold values to ensure users receive consistent results regardless of interface.

---

Summary

• Conservative GPS outlier filtering is the default mode in google-timeline-visualizer, activated automatically or via mode="conservative"
• Four hard-coded parameters govern removal: 3-point maximum runs, 1300 km/h speed ceiling, 200 m window distance, and 500 m neighbor proximity
• Control filtering through the --filter-outliers CLI flag or the filter_location_outliers() Python API
• Source implementation lives in visualizer.py with validated equivalents in the web TypeScript codebase

---

Frequently Asked Questions

How do I completely disable GPS outlier filtering?

Pass mode="off" to the Python function or use --filter-outliers off on the command line. This preserves every location point in your Timeline export without modification.

Why is the speed ceiling set to 1300 km/h?

The 1300 km/h threshold exceeds commercial jet cruise speeds while eliminating physically impossible coordinate jumps caused by GPS multipath or sensor glitches. Real flights remain unfiltered; sensor artifacts triggering supersonic implied speeds are removed.

What happens to outlier points longer than 3 consecutive readings?

Sequences of 4+ points bypass filtering entirely. The _suspicious_run_end logic (line 18 in visualizer.py) restricts examination to short isolated bursts, assuming longer runs represent actual travel rather than equipment error.

Can I adjust the filtering thresholds?

No—the conservative filter uses fixed values. The design philosophy emphasizes reproducibility and safety over customization. Users requiring different behavior must modify visualizer.py directly or implement custom preprocessing before calling filter_location_outliers().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}