🐧 maps-to-toggl

A practical import tool: Google Maps Timeline JSON → Toggl Track time entries.

If you already use location history (for example office/coworking visits), this script helps you backfill working time into Toggl with less manual work.

---

What is this for?

You were at the office, you worked, but Toggl was not running. Instead of adding everything by hand, this script reads your Google Timeline export and creates Toggl entries for locations you define.

Goal: less tedious admin, cleaner time tracking.

---

Features

• ✅ Supports both Google export formats:
  • timelineObjects (legacy)
  • semanticSegments (new)
• ✅ Location matching via
  • place_id (preferred) or
  • coordinates + tolerance (fallback)
• ✅ Merges overlapping intervals (per same description)
• ✅ Ignores short stays < 10 minutes
• ✅ Dry-run mode (preview only)
• ✅ Duplicate protection using overlap checks against existing Toggl entries
• ✅ Flexible configuration (CLI, config file, environment variables)

---

How it works (quick overview)

1. Export your Google Timeline data as JSON.
2. Define relevant locations in locations.json.
3. The script filters matching visits.
4. Intervals are cleaned/merged.
5. Existing Toggl entries are checked for overlap.
6. New non-overlapping entries are created in Toggl.

---

Export Google Maps Timeline JSON (Android)

Google likes to move menu items around, but the path is usually one of these:

Option A (inside Google Maps)

1. Open Google Maps
2. Tap your profile picture (top right)
3. Your Timeline
4. Tap the ⋮ menu (top right) → Settings and privacy
5. Find Export Timeline data (sometimes nested under Location & privacy settings)
6. Tap Export → Save

You should get a JSON (sometimes a ZIP containing JSON). Save it to your phone and then copy it to your computer (USB / cloud / whatever) and point the script at that file.

Option B (Android system settings path)

On some Android builds the Timeline export is linked via system location services:

• Android Settings → Location → Location services → Timeline → Export Timeline data

Fallback: Google Takeout (if the app export is missing)

• Go to https://takeout.google.com/
• Select Location History / Timeline
• Choose JSON export and download the archive

---

Requirements

• Python 3.10+
• Toggl Track API token
• Toggl Workspace ID
• Google Timeline export (JSON)

---

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create local config files:

cp locations.example.json locations.json
cp config.example.json config.json

locations.json and config.json are gitignored and stay local.

---

Configuration

1) Locations (locations.json)

Example:

[
  {
    "key": "office-main",
    "description": "Office",
    "place_id": "OPTIONAL_GOOGLE_PLACE_ID",
    "coords": [48.137154, 11.576124],
    "tolerance": 0.002
  }
]

Fields:

• key: internal identifier
• description: Toggl entry description
• place_id: optional, preferred when available
• coords: [lat, lng] fallback
• tolerance: matching tolerance in degrees (0.002 ≈ ~200m)

---

2) Workspace ID & API token (resolution order)

Workspace ID

1. --workspace-id
2. --config-file → toggl_workspace_id
3. TOGGL_WORKSPACE_ID (env)

API token

1. --config-file → toggl_api_token
2. TOGGL_API_TOKEN (env)

Example config.json:

{
  "toggl_workspace_id": 1234567,
  "toggl_api_token": "your_toggl_api_token"
}

---

Usage

Dry run (recommended first)

python maps_to_toggl.py ~/Timeline.json \
  --dry-run \
  --month 2026-02 \
  --locations-file locations.json \
  --workspace-id 1234567

Real import (using config file)

python maps_to_toggl.py ~/Timeline.json \
  --month 2026-02 \
  --locations-file locations.json \
  --config-file config.json

Environment-only setup

export TOGGL_WORKSPACE_ID=1234567
export TOGGL_API_TOKEN=...

python maps_to_toggl.py ~/Timeline.json --month 2026-02 --locations-file locations.json

---

CLI options

positional:
  file                    Path to Google Timeline JSON

optional:
  --dry-run               Preview only, do not write to Toggl
  --month YYYY-MM         Import only one month
  --year YYYY             Import only one year
  --locations-file PATH   Locations file (default: locations.example.json)
  --default-description   Fallback description (default: Office)
  --workspace-id INT      Toggl workspace ID (highest priority)
  --config-file PATH      Optional JSON config file

---

Security & privacy

• No hardcoded secrets in source code
• Local private files (locations.json, config.json, .env) are gitignored
• locations.json may contain sensitive location data
• Never commit real API tokens to public repositories

---

Known limitations

• Duplicate detection is based on time overlap (not Toggl entry IDs)
• Very large imports can be slow due to Toggl rate limits
• Coordinate matching quality depends on GPS accuracy + chosen tolerance

---

Troubleshooting

Config error: Missing TOGGL_API_TOKEN ...

Set token via one of these:

• TOGGL_API_TOKEN env
• config.json with toggl_api_token

Config error: Missing workspace id ...

Set workspace ID via:

• --workspace-id
• or config.json toggl_workspace_id
• or env TOGGL_WORKSPACE_ID

No entries found

• Check locations.json (coords/place_id)
• Increase tolerance if needed
• Verify --month / --year filters
• Start with --dry-run

---

Recommended workflow

1. Run monthly with --dry-run
2. Quickly verify output
3. Run real import
4. Add new places to locations.json when needed

That keeps Toggl accurate without painful manual reconstruction.

---

AI-assisted development disclaimer

Parts of this project were developed with assistance from generative AI tools. All generated code and text were reviewed and adapted by a human before publication.

---

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE for details.