Maps Timeline

Maps Timeline

View your Google Maps Timeline (location history) on an interactive map inside Obsidian — visits, movement routes, and your exact GPS tracks — with day, month and custom date‑range pickers. Your data never leaves your machine; map tiles come from OpenStreetMap or Esri (no key) or Google (your own key).

A two‑pane view: an interactive map on the left, a clickable timeline of that period on the right. Click any row to fly the map to it.

---

Features

• 🗺️ Interactive map of your location history — opens as its own pane, not a note.
• 📍 Visits as dots: 🟢 home · 🟣 work · 🔴 other. Click for name, time and duration.
• 🛣️ Real routes — your dense, road‑following GPS track (not a straight line between stops).
• ✈️ Flights drawn as a dashed line (because flights really are straight).
• 🗓️ Pickers — single day, ◀ ▶ stepping, Day / Week / Month quick buttons, or a custom from–to range.
• 🧭 Timeline sidebar — every visit and move for the period, grouped by day; click to focus on the map.
• 🏷️ Place names on demand — resolves coordinate‑only visits (Google's newer on‑device export has no names) via the Places API, cached locally so each place is fetched only once.
• 🌍 Basemaps — OpenStreetMap or Esri Satellite (free, no key), or Google Roadmap / Satellite / Hybrid / Terrain via your own key (Map Tiles API).
• ⚡ Canvas rendering — handles months of dense data without freezing.

Install

Manually

1. Download main.js, manifest.json, styles.css from the latest release.
2. Copy them into <your-vault>/.obsidian/plugins/maps-timeline/.
3. Settings → Community plugins → Maps Timeline → enable.

Via BRAT

Add jagajaga/obsidian-maps-timeline in the BRAT plugin.

Get your data

The plugin reads per‑year JSON files in a vault folder (default Maps/Timeline/data/). Generate them from your Google data once:

1. Export your timeline:
   • Takeout (history up to 2024): takeout.google.com → deselect all → Location History (Timeline) → export.
   • On‑device (recent months): Google Maps app → profile → Settings → Location & privacy / Timeline → Export Timeline data → Timeline.json.
2. Convert with the scripts in tools/ (see tools/README.md):

   pip install ijson
   MAPS_TAKEOUT=/path/to/export MAPS_OUT=/your-vault/Maps/Timeline/data python3 tools/maps_days.py
   MAPS_TAKEOUT=/path/to/export MAPS_OUT=/your-vault/Maps/Timeline/data python3 tools/maps_tracks.py
   

3. Point the plugin's Data folder setting at that folder.

The data format is simple — any converter producing the same shape works.

Usage

Open the map three ways: right‑click a year file (…/2018.json) → Open in Maps Timeline, the 🗺 ribbon icon, or the command Open Maps Timeline. Then pick a day, step with ◀ ▶, jump with Day / Week / Month, or type a custom range. Toggle the dense track layer off for very large ranges.

Settings

Data format

Each <year>.json is { "year": 2018, "days": { "YYYY-MM-DD": Day } }, where a Day is:

{
  "source": "old",
  "visits": [
    { "placeId": "ChIJ…", "name": "Caffè Terzi", "lat": 44.49, "lng": 11.34,
      "start": "2018-08-01T12:53:00Z", "end": "…", "minutes": 30, "semanticType": "TYPE_HOME" }
  ],
  "activities": [
    { "type": "IN_PASSENGER_VEHICLE", "km": 37.9, "start": [44.5,11.3], "end": [43.8,11.2],
      "startTime": "…", "path": [[lat,lng], …] }
  ],
  "paths": [ { "startTime": "…", "path": [[lat,lng], …] } ],
  "track": [ [lat,lng], … ]
}

name may be null for coordinate‑only visits — the plugin fills those in via the Places API and caches them.

Privacy

• Your location data lives only in your vault — the plugin never sends it anywhere.
• Your Google API key is stored locally and used only for Google tiles and Places‑name lookups, called directly from your client.
• OpenStreetMap / Esri Satellite modes use no key and make no Google calls.

Building

git clone https://github.com/jagajaga/obsidian-maps-timeline
cd obsidian-maps-timeline
npm install
npm run build      # bundles src/main.js + Leaflet -> main.js, and styles.css

Source lives in src/; main.js and styles.css are bundled outputs. Releases are built and attested by GitHub Actions (.github/workflows/release.yml).

Credits

• Leaflet (BSD‑2) — bundled map engine.
• Tiles: © OpenStreetMap contributors · © Esri · © Google (Map Tiles API).
• Interaction design inspired by kurupted/google-maps-timeline-viewer.

License

MIT. Bundled Leaflet retains its BSD‑2 license (see NOTICE).