# What Are the Three Distinct Export Formats Supported by TimelineParser?

> Discover the three distinct export formats TimelineParser supports: direct-array JSON, object-with-semanticSegments JSON, and raw-signals JSON for your Google Timeline data visualization needs.

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

---

**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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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.

```typescript
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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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.

```typescript
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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/web/src/timeline.ts) processes data with a `rawSignals` array. The parser validates this with `data.rawSignals` before extracting signal points.

```typescript
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`](https://github.com/mahlernim/google-timeline-visualizer/blob/main/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.