Coordinate Validation Bounds in Google Timeline Visualizer: A Complete Guide

Google Timeline Visualizer enforces strict latitude bounds of ‑85.05112878° to 85.05112878° and longitude bounds of ‑180° to 180° in its parse_coordinate function, rejecting any out-of-range values with None.

This open-source tool converts raw Google Timeline data into visual maps, and robust coordinate validation is essential to prevent malformed GPS entries from corrupting the rendering pipeline. The validation logic lives in visualizer.py, where the parse_coordinate helper processes every location string before it reaches the map engine.

---

Latitude and Longitude Limits Explained

The coordinate validation bounds in Google Timeline Visualizer follow geodetic standards with one critical Web Mercator constraint.

Latitude Range: ‑85.05112878° to 85.05112878°

The latitude bound of ±85.05112878° matches the mathematical limit of the Web Mercator projection. This prevents the projection formulas from producing infinite or undefined values near the poles.

In visualizer.py, the parse_coordinate function implements this check at lines 85–103:

from visualizer import parse_coordinate

# Valid coordinate (within bounds)

coord = parse_coordinate("37.7749,-122.4194")
print(coord)          # → (37.7749, -122.4194)

# Out‑of‑range latitude → rejected

coord = parse_coordinate("90.0,0.0")
print(coord)          # → None

Values beyond this range return None, causing the point to be silently dropped from the timeline.

Longitude Range: ‑180° to 180°

Longitude validation uses the standard ±180° geographic range. The parse_coordinate function parses the second component of each coordinate pair and validates:

# Out‑of‑range longitude → rejected

coord = parse_coordinate("0.0,200.0")
print(coord)          # → None

This aligns with global geographic conventions and ensures compatibility with mapping libraries.

---

Secondary Validation in latlon_to_meters

The coordinate validation bounds are reinforced during projection. The latlon_to_meters function (lines 12–16 of visualizer.py) clamps latitude values to the same ±85.05112878° range before converting to Web Mercator meters:

This defensive approach guarantees consistency even if malformed data bypasses the primary parser.

---

Legacy Integer Format Handling

Google Timeline Visualizer also normalizes legacy coordinate encodings. Some historical exports store latitude and longitude as scaled integers (multiplied by 10⁷). The parse_coordinate function auto-detects and rescales these:

# Legacy integer format (scaled by 10⁷) → auto‑scaled

coord = parse_coordinate("377749000, -1224194000")
print(coord)          # → (37.7749, -122.4194)

The heuristic triggers when absolute values exceed 1,000,000, dividing by 10,000,000 to recover decimal degrees before applying the standard coordinate validation bounds.

---

Why These Bounds Matter

Strict validation protects the visualization pipeline from three failure modes:

• Invalid map tiles – Out-of-range coordinates cause tile servers to return 404 errors
• Projection errors – Latitudes beyond ±85.05° break Web Mercator math
• Data corruption – A single malformed point can skew automatic viewport calculation

According to the mahlernim/google-timeline-visualizer source code, rejecting invalid coordinates at parse time is more reliable than attempting runtime fixes downstream.

---

Summary

• Latitude bounds: ‑85.05112878° ≤ lat ≤ 85.05112878° (enforced by parse_coordinate and latlon_to_meters)
• Longitude bounds: ‑180° ≤ lon ≤ 180° (enforced by parse_coordinate)
• Invalid handling: Out-of-range values return None and are excluded from rendering
• Legacy support: Integer coordinates >1,000,000 are auto-scaled by 10⁻⁷
• Source location: visualizer.py lines 12–16 and 85–103

---

Frequently Asked Questions

What happens when coordinates fail validation in Google Timeline Visualizer?

The parse_coordinate function returns None, and the point is silently skipped during timeline construction. This prevents invalid data from appearing on the map without crashing the entire visualization.

Why is the latitude limit ±85.05112878° instead of 90°?

This value represents the precise mathematical limit of the Web Mercator projection. Beyond this latitude, the tangent function in the projection formula approaches infinity, making reliable map rendering impossible.

Where is the coordinate validation code located?

All validation logic resides in visualizer.py. The parse_coordinate function (lines 85–103) handles initial parsing and bounds checking, while latlon_to_meters (lines 12–16) applies defensive clamping during coordinate projection.

Does Google Timeline Visualizer support non-decimal coordinate formats?

Yes. The parser automatically detects legacy integer formats where coordinates were stored multiplied by 10⁷. Values exceeding 1,000,000 are rescaled before the standard coordinate validation bounds are applied.

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