# Conservative GPS Outlier Filtering Parameters in google-timeline-visualizer

> Discover conservative GPS outlier filtering parameters for google-timeline-visualizer. Learn how 3 point run length, 1300 km/h speed ceiling, and distance thresholds clean location spikes.

- Repository: [mahlernim/google-timeline-visualizer](https://github.com/mahlernim/google-timeline-visualizer)
- Tags: how-to-guide
- Published: 2026-08-23

---

**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

```bash

# 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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py): `"conservative"` (default) or `"off"`.

### Python API Usage

```python
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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/outlier.ts)** — TypeScript version serving the web UI
- **[`web/src/outlier.test.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/outlier.test.ts)** — JavaScript test suite validating behavior
- **[`tests/test_outlier_filter.py`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/visualizer.py) directly or implement custom preprocessing before calling `filter_location_outliers()`.