- Google Timeline Visualizer converts exported Timeline JSON into animated MP4 travel videos.
- Android users install the APK from the repository’s latest GitHub release.
- iPhone users open the Safari web app without installing a native application.
- Privacy focus: Timeline JSON stays local, while map tiles are requested from CARTO.
- Best workflow: Restore missing history, export a small date range, preview it, then render.
google timeline visualizer GitHub Repository Overview
The google timeline visualizer github repository provides an open-source way to turn Google Location History Timeline data into an animated travel video. Instead of relying on a cloud dashboard, the tool reads a local Timeline.json file, lets you select a month range or exact dates, previews the journey, and creates an MP4 for watching or sharing.
The project supports Android and iPhone workflows, with a separate Python generator for desktop users. The Android app is distributed through GitHub releases rather than Google Play, while iPhone users can open the web app in Safari and add it to the home screen.
Video Highlights:
- Exporting Timeline JSON from Android or iPhone
- Running the visualizer locally instead of uploading the history file
- Previewing a route before creating an MP4
- Selecting camera movement and exact date ranges
- Saving completed videos to a local library
| Platform | Access method | Timeline file workflow | Output |
|---|---|---|---|
| Android | GitHub APK release | Export from Phone Settings | MP4 saved locally |
| iPhone | Safari web app | Export from Google Maps | MP4 available to play, share, or download |
| Desktop | Python command line version | Provide Timeline.json as input | Rendered travel video |
Android APK
- Download the latest
TimelineVisualizer-*.apk - Requires Android 8.0 or newer
- Disable install permission after setup
iPhone Web App
- Use Safari 16.4 or newer
- No native installation is required
- Timeline JSON remains on the device
Desktop Python
- Requires Python 3.9+
- Uses FFmpeg and project dependencies
- Useful for scripted or batch rendering
Use the official mahlernim/google-timeline-visualizer GitHub repository as the source for releases, documentation, privacy details, and build instructions. Avoid downloading APK files from third-party mirrors.
Export Your Google Timeline JSON
The visualizer needs an exported Timeline file. The export menus differ significantly between Android and iPhone, so follow the platform-specific route carefully. If the file contains no history, restore the Timeline in Google Maps first and export a new copy afterward.
| Device | Menu path | File name or location | Important note |
|---|---|---|---|
| Android | Phone Settings → Location → Location services → Timeline | Save Timeline.json in Downloads or another persistent folder | The export is handled through system settings |
| iPhone | Google Maps → Profile picture → Settings → Personal content → Export Timeline data | Save in the Files app | The JSON can also be moved to an Android device |
| Missing history | Google Maps restoration link | Restore before exporting again | The visualizer cannot access encrypted Google backups |
Check for Existing Timeline Data
Open Google Maps or the relevant Timeline settings and confirm that the device contains the travel history you expect. If you changed phones, reinstalled Maps, or reset the device, older trips may require restoration first.
Export on Android
Open Phone Settings, select Location, choose Location services, and open Timeline. Select Export Timeline data, continue through the confirmation screen, and save the resulting JSON file in an easy-to-find local folder.
Export on iPhone
Open Google Maps, tap the profile picture, select Settings, open Personal content, and choose Export Timeline data. Save the exported file inside Apple’s Files app.
Verify the File
Confirm that the file is accessible and contains the expected period. A zero-data export usually indicates that the local Timeline database has not been restored or populated.
If your phone shows different labels, use the repository’s Get Timeline file instructions. Android menu names can vary by manufacturer, and the app cannot provide a universal direct link to every device’s Timeline settings page.
If older trips disappeared after a device change, use Google Maps’ restoration flow first. Google Timeline Visualizer cannot sign in to your account or recover encrypted backup data directly.
Install and Protect the Local Workflow
The project is designed around local processing. Your Timeline JSON is not uploaded to a project server, and the app does not require Google Sign-In to read the exported file. The only network-dependent feature described by the project is basemap access.
Map tiles are requested from CARTO and use OpenStreetMap data. Those requests can reveal which map areas are being viewed to the tile provider, but they do not upload the Timeline JSON itself. Review the privacy notice before loading a file, especially when working with routes that expose home, workplace, or daily travel patterns.
| Privacy area | How the visualizer handles it | Practical recommendation |
|---|---|---|
| Timeline JSON | Processed locally and not uploaded | Keep the file in a protected folder |
| Google account | No Google Sign-In required | Export or restore through Google Maps separately |
| Basemap tiles | Requested from CARTO during map rendering | Review the map privacy notice before continuing |
| Rendered MP4 | Stored on the device | Share only after checking the route details |
| Original JSON | Left unchanged by filtering | Keep an untouched backup before experiments |
File Safety
Store the JSON locally, limit unnecessary sharing, and retain an untouched backup before editing or moving files.
Permission Hygiene
Android may require a temporary Install unknown apps permission. Revoke it after the APK is installed.
Sharing Review
Check the final route before sending an MP4. A travel animation can reveal sensitive locations and routines.
The app can apply Conservative GPS outlier filtering by default. This ignores isolated, implausible out-and-back coordinates while leaving the original JSON unchanged. You can turn filtering off when you need every location point included, but preview the result carefully before rendering.
Local processing protects the Timeline file from project-server uploads, but it does not make the finished MP4 anonymous. Review map tiles, route details, and sharing permissions before publishing a video.
Create an Animated Travel MP4
After loading the Timeline file, the main workflow is straightforward: choose the period, configure the visual style, preview the journey, and render the final video. Start with a short range or a small test period before processing several years of location history.
| Setting | Available choice | Best use |
|---|---|---|
| Date range | Month range or Exact dates | Use Exact dates for a trip or short event |
| Distance unit | Selectable unit | Match the unit used by your audience |
| Camera movement | Steady, Fixed, or Dynamic | Choose based on route complexity |
| GPS filtering | Conservative or Off | Remove isolated outliers or retain every point |
| Preview | Interactive journey preview | Confirm geometry before rendering |
| Output | MP4 and optional Journey overview | Watch, save, or share locally |
Open Create Video
Launch the Android app or iPhone web app and select Create video. Choose the exported Timeline file through the file picker.
Set the Date Range
Keep the default broad period for a year overview, or select Exact dates to isolate a vacation, road trip, or multi-day journey. Confirm that the selected range contains movement data.
Choose Camera Movement
Use Steady for a calmer route, Fixed when you want a locked altitude, or Dynamic when the route benefits from more aggressive scaling. Sparse long-distance travel is interpolated along a great-circle path.
Preview the Journey
Select Preview and inspect the route geometry, marker movement, and map coverage. If the path jumps unexpectedly, check the source data and filtering option before rendering.
Create and Save the MP4
Select Create video and monitor the rendering stages. On Android 10 and later, completed files are stored under Movies/Timeline Visualizer; Android 8 and 9 use the system Save As picker.
The application adds a short ending sequence that zooms out to reveal the complete route. On supported Android versions, you can switch apps or turn off the screen while rendering continues. Android 13 or newer can display progress notifications when notification access is allowed.
Preview a short date range first. This confirms file access, route geometry, camera behavior, and map loading before your device spends additional time rendering a large Timeline.
Video Library, Troubleshooting, and Desktop Tools
Completed MP4 files are added to My videos, where each entry can retain a thumbnail, Timeline period, duration, and creation date. Use Add videos to include earlier MP4 files. Removing an item from the list does not necessarily delete the underlying file, while Delete video is a separate confirmed action.
| Problem | Likely cause | Recommended fix |
|---|---|---|
| Export shows zero data | Local Timeline is empty | Restore history in Google Maps, then export again |
| APK installation is blocked | Unknown-app permission is disabled | Temporarily allow the browser or file manager |
| Route contains strange jumps | GPS outliers or sparse data | Preview with Conservative filtering enabled |
| File cannot be reopened | File moved or provider access lost | Repeat the normal file-loading flow |
| Video entry says unavailable | MP4 was moved or deleted externally | Remove the stale library entry or restore the file |
| Render is too large to test | Date range includes excessive history | Use Exact dates for a smaller validation render |
For desktop automation, the repository retains the original Python generator. The documented setup uses Python 3.9 or newer, FFmpeg, and packages from requirements.txt.
python -m pip install -r requirements.txt
python visualizer.py --input Timeline.json --year 2026 --camera-movement steady
The command-line workflow is useful when you want repeatable rendering or batch conversion. Keep the input path local, verify the selected year or period, and confirm that FFmpeg is available before beginning a long render.
Before You Render:
- Confirm the Timeline JSON contains the intended travel period
- Restore missing Google Maps history before exporting again
- Preview a short date range and inspect route geometry
- Review the privacy notice and visible map areas
- Revoke Android install permission after installing the APK
Use My videos for organization, but remember that a library entry and the MP4 file are separate concerns. Check the file location before removing or deleting an entry.
Google Timeline Visualizer FAQ
Q: Does Google Timeline Visualizer upload my Timeline JSON?
The project documentation states that the Timeline file is never uploaded. Processing happens locally. Basemap tiles are requested from CARTO, and those requests may reveal viewed map areas to the tile provider.
Q: Can I use the visualizer on an iPhone?
Yes. Open the iPhone web app in Safari, choose the exported Timeline.json from Files, select the date range and camera movement, preview the journey, and create the MP4. No native app installation is required.
Q: Where should Android users download the APK?
Download the latest TimelineVisualizer APK from the Assets section of the official mahlernim/google-timeline-visualizer GitHub release. Do not select the checksum file, and avoid third-party mirrors.
Q: Why did my older trips disappear?
A phone change, Google Maps reinstall, or device reset can leave the local Timeline database empty. Restore the encrypted history in Google Maps first, then export a fresh Timeline JSON file for the visualizer.
The repository also documents support for current direct-array Timeline exports, older semanticSegments structures, paths, activities, visits, several coordinate formats, and routes crossing the international date line. Raw-location fallback may display a warning because semantic processing is unavailable.
For broader account and Timeline recovery instructions, consult Google’s official Timeline Help. Use the GitHub repository for the visualizer’s release files, privacy explanation, platform instructions, and development documentation.
The safest workflow is to treat Google Maps as the place to restore or export history, and the GitHub visualizer as the local tool for previewing and rendering that exported file.