- Primary keyword: google timeline visualizer source code covers Android, iPhone web, and desktop workflows.
- Core input: Export a local
Timeline.jsonfile before creating an animated journey video. - Desktop setup: Install Python 3.9+, FFmpeg, and the packages listed in
requirements.txt. - Android build: Use JDK 17, Android SDK Platform 36, and Build Tools 36.0.0.
- Privacy model: Timeline data stays local while basemap tiles are requested from CARTO.
google timeline visualizer source code Overview
The Google Timeline Visualizer repository on GitHub is a source-available project for turning an exported Google Maps Timeline file into an animated travel video. It is not a conventional game or entertainment platform. Its main focus is local Timeline processing, animated map rendering, MP4 creation, and privacy-conscious file handling.
The project provides an Android application, an iPhone web app, and an original desktop Python generator. The same general workflow applies across these versions: export Timeline data, select a period, preview the route, and render a video.
| Component | Primary role | Main environment |
|---|---|---|
| Android app | Import Timeline files and render MP4 videos | Android 8.0 or newer |
| iPhone web app | Process an exported JSON file in Safari | iPhone Safari |
| Desktop generator | Create videos from the command line or Python workflow | Desktop with Python |
| Repository build tools | Test, lint, and assemble Android variants | JDK 17 and Android SDK |
Local File Processing
Timeline JSON is selected from device storage. The project does not copy the source file into an account-based cloud workflow.
Animated Journeys
A route marker follows the selected travel history, with interpolation for sparse trips and camera movement controls.
Video Library
Completed MP4 files can be indexed, watched, shared, moved, or deleted through the application interface.
Treat this project as a local visualization pipeline. The important setup decisions involve file access, rendering dependencies, map tiles, and build tools rather than account login.
Timeline Export and Input Formats
The visualizer requires an exported Timeline file. On iPhone, export the data from Google Maps through Profile picture → Settings → Personal content → Export Timeline data. Save the resulting Timeline.json file in the Files app, then select it from Safari.
On Android, the export is handled through the phone’s Settings app rather than directly inside Google Maps. Open Settings → Location → Location services → Timeline, choose Export Timeline data, and save the file in a convenient location such as Downloads.
| Platform | Export path | Next action |
|---|---|---|
| iPhone | Google Maps personal content settings | Open the web app in Safari |
| Android | Phone Settings, Location services, Timeline | Select the JSON file in the app |
| Desktop | Copy an exported Timeline file to the computer | Pass the file to the Python generator |
| Restored history | Restore history in Google Maps first | Export a new JSON file afterward |
The source supports current Android and iOS direct-array exports as well as older files using a semanticSegments structure. It can also recognize several coordinate representations, including string values, latLng, degree-based values, geo: coordinates, and E7 coordinates.
Supported route data may include:
- Timeline paths
- Activities
- Visits
- Sparse long-distance routes
- Routes crossing the international date line
- Optional raw location data with a warning and local noise reduction
If older trips are missing after a phone change or reset, restore the history in Google Maps first. Timeline Visualizer cannot access Google’s encrypted backup directly.
For official export and restoration guidance, consult Google Maps Timeline Help, reviewed for this guide on August 25, 2026.
Step-by-Step Setup and Video Rendering
The fastest workflow is to prepare the JSON file, select a date range, preview the route, and create the MP4. Exact menu names can vary slightly by phone model, but the project keeps the central process consistent.
Prepare Timeline.json
Export your Timeline history from Google Maps or Android Location settings. Keep the file in a location that the browser, file manager, or application can access.
Choose the Journey Range
Open the video creation flow, select the Timeline file, and choose a month range or exact dates. Exact dates are useful for isolating a short trip.
Configure the Preview
Select the distance unit and camera movement style, then preview the animated route. Review the map motion before starting the final render.
Create the MP4
Start video creation and monitor progress. The app displays stages, may estimate remaining time, and provides a cancel option during rendering.
Save or Share the Result
Open the finished video from the local library, play it, share it, or use the save controls to copy it elsewhere.
| Setting | Available behavior | Practical use |
|---|---|---|
| Date range | Month range or exact dates | Focus on a single journey or broader history |
| Distance unit | Selectable unit | Match the audience and region |
| Camera movement | Configurable movement style | Use steady motion for easier viewing |
| GPS filtering | Conservative by default, or Off | Reduce isolated implausible out-and-back points |
| Preview | Interactive route preview | Check timing and map movement before rendering |
During rendering, older travel fades behind the moving marker so longer Timelines remain easier to follow. Sparse routes, including long flights, are interpolated along a great-circle path. Local travel can keep the marker within a stable central area before the camera follows it, which reduces rapid camera movement on commutes.
The final video adds a 1.5-second zoom-out ending that reveals the complete route and holds the overview briefly. On Android 10 and later, completed files are saved under Movies/Timeline Visualizer. Android 8 and 9 use the system Save As picker.
Preview the entire journey before creating the final MP4. This helps identify an overly broad date range, unexpected GPS points, or camera movement that does not suit the route.
Desktop Python Version and Android Builds
The original desktop generator remains available for users who prefer Python-based processing. The documented requirements are Python 3.9 or newer, FFmpeg, and the packages in requirements.txt.
A basic dependency setup is:
python -m pip install -r requirements.txt
The repository documentation also provides a Python invocation pattern using visualizer.py, an input Timeline file, a selected year, and a camera movement option:
python visualizer.py --input Timeline.json --year 2026 --camera-movement steady
Use the command as a starting point and confirm the current repository arguments before scripting a larger batch. File paths, date selections, and available options should match the checked-out revision.
| Build target | Required tools | Validation command |
|---|---|---|
| Desktop Python generator | Python 3.9+, FFmpeg, requirements.txt | Run the Python generator with an exported JSON file |
| Android debug build | JDK 17, Android SDK Platform 36 | ./gradlew assembleGithubDebug |
| Android Play build | JDK 17, Android SDK Platform 36 | ./gradlew assemblePlayDebug |
| Android quality checks | Gradle toolchain | ./gradlew test lint |
| Python tests | Development requirements | python -m pip install -r requirements-dev.txt and python -m pytest |
For Android development, the documented toolchain includes JDK 17, Android SDK Platform 36, and Build Tools 36.0.0. The repository test sequence combines Android validation with Python dependency installation and pytest execution.
Pin your local JDK, Android SDK, Build Tools, Python, and FFmpeg versions where possible. Consistent tooling makes rendering and release troubleshooting easier.
The Android application is distributed through repository releases rather than Google Play in the referenced documentation. If installing an APK directly, download the release asset from the repository and avoid checksum files when selecting the install package. Android may display an outside-Play warning for this distribution method.
Privacy, Storage, and Troubleshooting
Privacy is a central part of the project’s design. The Timeline JSON file is not uploaded. The only network-dependent feature described in the project is the basemap: CARTO receives requests for displayed map areas and serves tiles based on OpenStreetMap data.
This means the route file and map tiles should be considered separately:
| Data or service | Project behavior | Privacy consideration |
|---|---|---|
| Timeline JSON | Processed locally | The file is not uploaded by the app |
| Google Sign-In | Not required for Timeline access | Sign-In cannot expose phone Timeline history |
| CARTO basemap | Requests visible map areas | Tile requests reveal viewed map regions |
| MP4 output | Saved locally | Share or move files intentionally |
| Video index | Stores local metadata and thumbnails | Removing an entry does not necessarily delete the MP4 |
The app keeps a small local index for completed videos. Entries can include a thumbnail, title, Timeline period, duration, and creation date. Remove from list leaves the MP4 untouched, while Delete video is a separate confirmed action that can permanently remove the file when the storage provider allows it.
Use this troubleshooting sequence when a workflow fails:
- If the Timeline menu is missing, check the phone’s Location settings and consult Google’s current help labels.
- If a file cannot be reopened, verify that it was not moved and that storage permission remains available.
- If an old trip is absent, restore it in Google Maps and export a new JSON file.
- If a preview looks unstable, review GPS filtering and camera movement settings.
- If an APK will not install, verify the Android version and temporarily allow installation from the selected browser or file manager.
Source Code Setup Checklist:
- Export a fresh Timeline.json file
- Confirm the selected date range and coordinate format
- Install Python, FFmpeg, or the Android build toolchain as needed
- Preview the route before rendering the MP4
- Review map privacy and local video storage settings
Although the Timeline file remains local, basemap requests can reveal the areas displayed in the preview or exported video. Review the map privacy notice before loading sensitive history.
FAQ
Q: What does the google timeline visualizer source code create?
It supports tools that turn exported Google Maps Timeline data into animated travel videos, including an Android app, an iPhone web app, and a desktop Python generator.
Q: Does Timeline Visualizer upload my Timeline.json file?
The project documentation states that the Timeline file is never uploaded. The basemap is the network feature, and CARTO receives requests for displayed map areas.
Q: What is required to build the Android project?
The documented Android requirements are JDK 17, Android SDK Platform 36, and Build Tools 36.0.0. The repository also provides Gradle commands for testing, linting, and assembling builds.
Q: Can the project restore missing Google Maps Timeline history?
No. Restore the history in Google Maps first, then export a new JSON file. Timeline Visualizer cannot directly access Google’s encrypted backup.
Keep the exported JSON, generated MP4, and source repository version documented separately. That makes future re-renders easier without confusing source data with finished media.