# How the Visualizer Handles Different Coordinate Formats in Google Timeline JSON

> Discover how the google-timeline-visualizer handles various coordinate formats. Learn how parseCoordinate normalizes iOS degrees, geo URIs, and E7 integers into decimal degrees.

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

---

**The `google-timeline-visualizer` parses diverse location representations through a single resilient function `parseCoordinate` in [`web/src/timeline.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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)](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.

```typescript
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.

```typescript
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.

```typescript
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.

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

```

## The Normalization Pipeline

The complete parsing flow in [`web/src/timeline.ts`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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)](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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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)](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)](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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/types.ts).