How the Visualizer Handles Different Coordinate Formats in Google Timeline JSON

The google-timeline-visualizer parses diverse location representations through a single resilient function parseCoordinate in web/src/timeline.ts that normalizes iOS degree strings, geo: URIs, nested objects, and Google's E7 micro-degree integers into standardized decimal degree tuples.

The mahlernim/google-timeline-visualizer processes location history exports from Google Timeline, which encode coordinates in multiple inconsistent formats. Understanding how the visualizer handles different coordinate formats in Google Timeline JSON reveals a robust normalization pipeline implemented in TypeScript that converts everything from Unicode degree symbols to scaled integer micro-degrees into clean latitude/longitude pairs.

The Core parseCoordinate Function

The central logic resides in parseCoordinate, defined at lines 27–53 of [web/src/timeline.ts](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/timeline.ts). This function accepts unknown input and returns either a [number, number] tuple representing [latitude, longitude] or null when parsing fails.

According to the source code, the function is intentionally format-agnostic, employing a cascading detection strategy that strips decorative characters, resolves URI schemes, flattens object nesting, and rescales Google's internal coordinate representations.

Supported Coordinate Format Types

The visualizer specifically handles four distinct representations found in Timeline exports.

iOS Degree Strings with Unicode Symbols

When Google Timeline data originates from iOS devices, coordinates often appear as strings containing the degree symbol. The parser removes trailing ° characters using replaceAll('°', ''), eliminates whitespace, and splits the remaining values on commas.

parseCoordinate('37.5°, 127.0°');
// Returns: [37.5, 127]

Standard geo: URIs

Android and web exports frequently use RFC 5870 geo: URIs that include optional zoom parameters. The function strips the geo: prefix with replace(/^geo:/, '') and removes query strings after ? before parsing the comma-separated coordinates.

parseCoordinate('geo:37.5,127?z=12');
// Returns: [37.5, 127]

Nested Objects with latLng Properties

Timeline JSON sometimes wraps coordinates in objects containing latLng or point properties. In these cases, parseCoordinate recursively calls itself on the nested value to extract the underlying string.

parseCoordinate({ latLng: '37.5,127' });
// Returns: [37.5, 127]

Google's E7 Micro-Degree Integers

Google's internal "E7" format stores coordinates as integers scaled by 10,000,000 (micro-degrees). After initial parsing, if either absolute value exceeds 1,000,000, the function divides by 10,000,000 to convert back to decimal degrees.

parseCoordinate('375000000,1270000000');
// Returns: [37.5, 127]

The Normalization Pipeline

The complete parsing flow in web/src/timeline.ts (lines 31–52) executes eight distinct validation and transformation steps:

1. Object handling – If the input is an object, extract latLng or point and recurse.
2. String validation – Return null immediately for empty or non-string inputs.
3. Cleaning – Remove whitespace, the geo: scheme, query parameters, and degree symbols.
4. Splitting – Separate the cleaned string on commas; require at least two parts.
5. Numeric conversion – Cast both parts to Number; return null for non-finite results.
6. E7 detection – Values greater than 1,000,000 are assumed to be micro-degrees and scaled down.
7. Range checking – Enforce latitude within [-85.05112878, 85.05112878] and longitude within [-180, 180]; reject out-of-range values.
8. Result – Return the [latitude, longitude] tuple or null for malformed input.

Validation and Error Handling

The visualizer implements strict range validation to ensure geographic sanity. Coordinates outside Earth's valid ranges return null rather than corrupted data. For example, latitude values exceeding 85.05112878 degrees or completely malformed strings like 'not a coordinate' result in null returns, preventing invalid points from entering the visualization pipeline.

Integration with the GeoPoint System

Once normalized, coordinates are wrapped into GeoPoint objects defined in [web/src/types.ts](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/types.ts). The addPoint function consumes these tuples alongside timestamp data, enabling the visualizer to render trajectories, calculate distances, and filter timelines accurately.

Summary

• The parseCoordinate function in web/src/timeline.ts serves as the single entry point for all coordinate normalization.
• The visualizer supports iOS degree strings, geo: URIs, nested objects, and E7 micro-degree integers.
• Invalid inputs and out-of-range coordinates consistently return null to maintain data integrity.
• All parsed coordinates are converted to decimal degrees and encapsulated as GeoPoint types for downstream visualization.

Frequently Asked Questions

What coordinate formats does Google Timeline JSON export use?

Google Timeline exports contain coordinates in four primary formats: iOS-style strings with degree symbols (e.g., "37.5°, 127.0°"), standard geo: URIs with optional query parameters, objects containing latLng or point properties, and E7 integer micro-degrees (e.g., "375000000,1270000000"). The visualizer handles all variations through its tolerant parser.

How does the visualizer handle invalid coordinates?

The parseCoordinate function returns null for any input that fails validation. This includes non-finite numeric values, coordinates outside valid latitude/longitude ranges, or malformed strings. This strict null-return policy prevents corrupt data from being added to the visualization via the addPoint function.

What is the E7 format in Google Timeline data?

E7 is Google's internal coordinate representation that stores degrees as integers multiplied by 10,000,000 (micro-degrees). The visualizer detects E7 values by checking if the absolute value exceeds 1,000,000, then divides by 10,000,000 to convert back to standard decimal degrees suitable for mapping libraries.

Where is the coordinate parsing logic located in the source code?

The core logic resides in [web/src/timeline.ts](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/timeline.ts) at lines 27–53, with comprehensive test coverage in [web/src/timeline.test.ts](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/timeline.test.ts) lines 15–21. The GeoPoint type definition lives in web/src/types.ts.

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