- Google Timeline Visualizer Python turns exported Timeline JSON into locally rendered travel videos.
- Desktop setup requires Python 3.9 or newer, FFmpeg, and the project dependencies.
- Format support includes current exports, older semantic segments, activities, visits, and several coordinate styles.
- Route smoothing uses conservative outlier filtering and great-circle interpolation for sparse journeys.
- Privacy note: Timeline JSON stays local, while map tile requests can reveal viewed regions to the tile provider.
google timeline visualizer python: What It Does
The desktop Python version is a local rendering tool for Google Maps Timeline exports. It reads a saved Timeline.json file, interprets location points and route information, then produces an animated map video. This makes it useful for reviewing past trips without uploading the Timeline document to a third-party application.
The tool is best understood as a retrospective renderer rather than a live tracking service. It does not continuously collect new movements, connect to a Google account, or restore encrypted Timeline backups. Prepare and restore your history in Google Maps first, export the file, and then use the visualizer to create a video.
Video Highlights:
- Local parsing of fragmented Google Timeline export formats
- Conservative filtering for isolated GPS outliers
- Great-circle interpolation for long flights and sparse routes
- Stable camera movement designed to reduce map shaking
- Local video rendering through a desktop Python workflow
Local Rendering
Timeline data is processed on the device instead of being uploaded as a complete history file.
Route Animation
The renderer creates cinematic movement across selected dates, including long-distance journeys.
Schema Translation
The parser handles multiple export structures, coordinate representations, and older Timeline formats.
Use the Python version when you want desktop control, repeatable commands, and direct access to the generated MP4 files.
| Capability | Desktop Python Version | Practical Result |
|---|---|---|
| Input | Exported Timeline.json | Uses a local copy of your Timeline history |
| Output | Animated video through FFmpeg | Creates a shareable MP4 |
| Processing | Python command-line workflow | Suitable for repeatable desktop jobs |
| Tracking | Retrospective only | Does not append ongoing location data |
| Account access | Not supported | Google login is not required |
Python Setup and File Preparation
Before launching the renderer, install the required desktop tools and place your Timeline export in an easy-to-find directory. The documented desktop workflow requires Python 3.9 or newer, FFmpeg, and packages listed in requirements.txt.
The input file should be exported from Google Maps or restored there before export. The visualizer cannot open Google’s encrypted mobile backup directly, and it cannot access your account to recover missing history.
Keep an untouched backup of Timeline.json. Filtering affects the rendering process only; the original JSON remains unchanged, but a separate backup protects against accidental file operations.
Export Timeline Data
Export Timeline data from the device or Google Maps workflow available on your account. On Android, the documented path begins in Phone Settings under Location, Location services, and Timeline. On iPhone, export through Google Maps personal content settings and save the JSON in Files.
Install Python Dependencies
Confirm Python 3.9 or newer, then run python -m pip install -r requirements.txt from the project directory. This installs the packages required by the desktop generator.
Install FFmpeg
Add FFmpeg to the desktop environment and confirm that the command is available from your terminal. FFmpeg handles the video compilation stage and supports multithreaded processing.
Place the JSON File
Copy or move Timeline.json into a known folder. Use the full path if the terminal is operating from a different directory.
Run a Focused Render
Start with a limited year or date range and a steady camera option. Review the result before attempting a large, multi-year export.
| Setup Item | Requirement | Check |
|---|---|---|
| Python | 3.9 or newer | Run python --version |
| Video engine | FFmpeg | Confirm it runs from the terminal |
| Packages | requirements.txt | Install with pip |
| Input | Timeline.json | Keep the original backup |
| First render | Limited range | Test before a long export |
A documented command pattern is:
python visualizer.py --input Timeline.json --year 2025 --camera-movement steady
The example uses a 2025 year filter from the project instructions. For a current 2026 workflow, choose the year or date range that matches the exported data you want to visualize. If your project version exposes additional date arguments, use its local help output to confirm the exact syntax.
A short trip is the safest first render. It confirms that Python, FFmpeg, the input path, map access, and output permissions are working before a longer job consumes more time.
Supported Timeline Formats and Route Controls
Google Timeline exports can vary by device, account history, and export generation. The visualizer is designed to normalize several structures instead of assuming that every file uses one coordinate schema.
Supported inputs include current direct-array exports, older files using semanticSegments, paths, activities, visits, and optional raw location data. Coordinate values may appear as strings, latLng values, degree fields, geo: strings, or E7 integer coordinates.
| Timeline Input | Handling | Recommended Action |
|---|---|---|
| Current direct-array export | Parsed as the modern Timeline structure | Use the exported JSON directly |
semanticSegments export | Translated from the older nested format | Test a short date range first |
| Paths, activities, visits | Used to build route context | Keep relevant journey periods selected |
| Raw location fallback | Parsed with a warning and local noise reduction | Inspect the filtered point count |
| E7 coordinates | Converted into usable latitude and longitude | Preserve the source file unchanged |
The default GPS setting is Conservative GPS outlier filtering. It ignores isolated, implausible out-and-back points that could create sharp spikes or false detours. The method is intended to improve readability without rewriting the source data.
You can turn filtering off when every recorded point matters. This may be useful for technical inspection, but it can also make the animation less stable when the Timeline contains GPS bounce from buildings, weak signals, or temporary positioning errors.
The outlier filter is a rendering preference. It changes which points appear in the generated visualization, while the original Timeline file remains available for later processing.
For long flights and other sparse routes, the renderer uses great-circle interpolation. Instead of drawing a visually awkward straight streak across a flat map, the route follows the shortest path over a sphere. This is especially useful for journeys that cross the international date line.
The camera also uses a stable movement model. A marker can travel within a central viewing area while the map stays steady. When the marker reaches the boundary, the camera begins following it. This reduces rapid back-and-forth panning during local commutes.
| Control | Purpose | Best Starting Choice |
|---|---|---|
| Date range | Limits the journey shown | Exact dates for a single trip |
| Year filter | Selects a calendar year | Use one year for an initial test |
| Camera movement | Controls map following behavior | Steady for calm travel footage |
| GPS filtering | Removes isolated implausible points | Conservative by default |
| Distance unit | Changes displayed travel measurements | Match your audience or region |
A narrow date range usually produces a clearer story than rendering an entire year. Use a full-year view when the goal is a broad travel overview rather than a single journey.
Rendering, Review, and Video Management
After loading the file, select the journey period, camera movement, and distance unit before previewing. The preview is interactive and helps identify missing points, unwanted GPS spikes, or a route that is too broad for the intended video.
The saved video uses the selected design and prepares map tiles before rendering. On Android, the related application stores completed MP4 files in a dedicated movie folder, while the original desktop workflow writes the result according to the project’s output behavior and local permissions.
For the Python workflow, keep the terminal open during the first render so errors are visible. A short test can expose a missing dependency, an unavailable FFmpeg command, a malformed path, or an input file that does not match the expected export structure.
Do not begin with a decade of location history unless a short test already works. Large files may include many points and require substantially more processing and temporary storage.
Before Creating the Final Video:
- Keep an untouched backup of Timeline.json
- Confirm Python 3.9 or newer and FFmpeg are available
- Test a short date range or single trip
- Review GPS filtering and camera movement
- Check the exported MP4 and its map attribution
| Review Stage | What to Inspect | Why It Matters |
|---|---|---|
| File load | Dates and detected locations | Confirms the export can be parsed |
| Preview | Route shape and camera stability | Reveals spikes or excessive movement |
| Filter report | Number of ignored points | Helps explain route differences |
| Render | Progress and final output | Confirms FFmpeg completed successfully |
| Final video | Playback, attribution, and sharing copy | Prevents publishing an unintended route |
The application ecosystem also supports a local video library for completed MP4 files, thumbnails, titles, periods, duration, and creation dates. If you move or delete a video outside the library, its entry may become unavailable. Removing an entry from a list is separate from permanently deleting the underlying file.
For private travel records, review the finished video before sharing. A route animation can reveal homes, workplaces, regular commutes, medical visits, or other sensitive locations even when the original JSON never leaves your computer.
Create separate videos for selected trips instead of publishing a complete location history. This preserves the visual story while reducing unnecessary exposure of sensitive movements.
Privacy Limits and Alternative Workflows
The local-first design keeps the Timeline JSON on the device during processing. However, map backgrounds require external tile requests. The documented privacy explanation identifies CARTO as the basemap provider, with map data based on OpenStreetMap. Requests for displayed areas can reveal the regions being viewed to that provider.
Before the first map tile loads, review the privacy notice and decide whether the tradeoff fits your use case. Local processing reduces the need to upload the full history, but it does not make every network interaction invisible.
| Data Element | Local or External | Privacy Consideration |
|---|---|---|
| Timeline JSON | Local processing | Not uploaded by the visualizer |
| GPS parsing | Local | Coordinates are interpreted on the device |
| Map tile requests | External | Viewed regions may be visible to the tile provider |
| Rendered MP4 | Local output | Sharing it can reveal the route visually |
| Google account backup | Separate Google service | Restore it in Google Maps before exporting |
Users seeking persistent storage should distinguish a visualizer from a self-hosted location database. The visualizer is ephemeral: it reads data, renders a video, and is designed for retrospective use. A self-hosted spatial system serves a different purpose by continuously storing location history and supporting longer-term analytics.
A practical hybrid approach is to maintain a private system for ongoing records, then use the visualizer only when a cinematic export is needed. Migration utilities can also help merge overlapping exports or convert proprietary structures into more portable geographic formats, but each tool should be reviewed before entrusting it with sensitive data.
For software development, the repository includes test and build guidance for both the desktop and Android projects. Python development dependencies can be installed with python -m pip install -r requirements-dev.txt, followed by the project’s test command. Android build requirements are separate from the Python workflow.
The Timeline document can remain local while basemap requests still leave the device. Treat the privacy notice, tile provider, and final MP4 as separate parts of your threat model.
For implementation details, consult the Google Timeline Visualizer GitHub repository. The repository documents supported workflows, installation notes, privacy behavior, build commands, and the MIT license.
FAQ: Google Timeline Visualizer Python
Q: What is Google Timeline Visualizer Python used for?
It is a desktop rendering workflow that reads an exported Google Timeline JSON file and creates an animated travel video through Python and FFmpeg. It is intended for retrospective visualization, not continuous tracking.
Q: What does the Python version require?
The documented desktop version requires Python 3.9 or newer, FFmpeg, and the packages listed in requirements.txt. Install the packages with python -m pip install -r requirements.txt before running the generator.
Q: Can it restore a missing Google Maps Timeline backup?
No. Restore an encrypted backup in Google Maps first, then export a new Timeline JSON file. The visualizer cannot access your Google account or open the encrypted backup directly.
Q: Does the visualizer upload my Timeline file?
The documented workflow processes the Timeline file locally and does not upload it. Map tiles are a separate network feature, so the tile provider may learn which map areas are requested.
Start with a short export, use conservative filtering, preview the route, and keep both the original JSON and final MP4 under your control.