What Are the Three Distinct Export Formats Supported by TimelineParser?

TimelineParser supports three distinct export formats: direct-array JSON, object-with-semanticSegments JSON, and raw-signals JSON.

The TimelineParser in the mahlernim/google-timeline-visualizer project handles multiple Google Timeline export structures. Understanding these formats ensures your data loads correctly regardless of how you exported it from Google Takeout or other sources.

Direct-Array Export Format

The simplest format is a plain JSON array where each element represents a timeline segment.

In web/src/timeline.ts, the parseTimelineJson function detects this format at lines 85-89 using Array.isArray(data). When the input is an array, the parser processes each element directly as a timeline segment.

import { parseTimelineJson } from './timeline';

// Direct-array export: plain array of segments
const rawArray = [
  { startTime: "2023-01-01T08:00:00Z", endTime: "2023-01-01T09:00:00Z" },
  { startTime: "2023-01-01T10:00:00Z", endTime: "2023-01-01T11:00:00Z" }
];

const points = parseTimelineJson(rawArray);

This format works well when you have pre-filtered or custom-processed timeline data stored as a simple array.

Semantic-Segments Export Format

The standard Google Takeout format wraps segments in an object with a semanticSegments property.

According to the source code at lines 89-91 in web/src/timeline.ts, parseTimelineJson checks for isObject(data) && Array.isArray(data.semanticSegments) to identify this structure. This is the format Google generates when you export your Timeline data through Google Takeout.

import { parseTimelineJson } from './timeline';

// Semantic-segments export: Google Takeout format
const takeoutData = {
  semanticSegments: [
    { 
      startTime: { timestamp: "2023-01-01T08:00:00Z" },
      endTime: { timestamp: "2023-01-01T09:00:00Z" },
      visit: { topCandidate: { placeId: "ChIJ..." } }
    }
  ]
};

const points = parseTimelineJson(takeoutData);

Most users encounter this format when working with official Google Timeline exports.

Raw-Signals Export Format

The third format handles raw location signals through a dedicated parsing routine.

While parseTimelineJson handles the first two formats, parseRawSignalsJson at lines 300-302 in web/src/timeline.ts processes data with a rawSignals array. The parser validates this with data.rawSignals before extracting signal points.

import { parseRawSignalsJson } from './timeline';

// Raw-signals export: underlying location data
const rawSignalsData = {
  rawSignals: [
    {
      position: { 
        LatLng: "37.7749° N, 122.4194° W",
        timestamp: "2023-01-01T08:00:00Z"
      }
    }
  ]
};

const signalPoints = parseRawSignalsJson(rawSignalsData);

Raw signals contain lower-level location data without the semantic interpretation that segments provide.

How TimelineParser Detects Each Format

The parser uses a cascading detection strategy in parseTimelineJson:

1. Array check first — if Array.isArray(data) passes, treat as direct-array
2. Object with semanticSegments — else if isObject(data) && Array.isArray(data.semanticSegments), extract the array
3. Fallback — throws an error for unrecognized structures

For raw signals, you must explicitly call parseRawSignalsJson since it uses a different data model and returns different point types.

Summary

• Direct-array export: Plain JSON array parsed by parseTimelineJson — simplest structure, minimal nesting
• Semantic-segments export: Google Takeout format with semanticSegments property — most common for official exports
• Raw-signals export: rawSignals array processed by parseRawSignalsJson — lower-level location data

Frequently Asked Questions

How do I know which export format my Timeline data uses?

Check the top-level structure of your JSON file. If it starts with [ (square bracket), it's a direct-array export. If it starts with { (curly brace), look for semanticSegments or rawSignals keys. The mahlernim/google-timeline-visualizer test suite in timeline.test.ts provides sample structures for comparison.

Can parseTimelineJson handle raw-signals data?

No. Raw-signals data requires the separate parseRawSignalsJson function because the data structure differs significantly. Raw signals contain position objects with LatLng strings rather than the processed visit or activity objects found in semantic segments.

Which export format should I use for best accuracy?

Use the semantic-segments export from Google Takeout for most applications. It provides processed, deduplicated location history with semantic meaning (visits, activities). Raw signals contain more noise and duplicate points from multiple location sources but offer higher temporal resolution when you need unfiltered data.

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