Timeline Visualizer: Google Timeline JSON to an Android Travel Video

What Timeline Visualizer solves, and for whom

Google Location History is a record, not a story. The export is a JSON file, and reading it in a text editor tells you almost nothing about a year of movement. Timeline Visualizer takes that file and produces an animated map video: a marker travels the route, older travel fades behind it, and an ending zooms out to reveal the complete journey. The output is an MP4 you can watch or share.

The audience is narrow and clearly defined. You need a Google Timeline export in hand, an Android phone running 8.0 or newer, and enough patience to pick a date range and wait through a render. On iPhone the project offers a web app instead of an app, and the README states plainly that there is no app to install and no Timeline file is uploaded. That sentence is the whole privacy argument, and it is worth more than a policy page.

The project is written in Kotlin, licensed MIT, and ships both an Android application under app/ and a Python script, visualizer.py, at the repository root. The README is available in Korean and Japanese alongside English, which matches the app's apparent user base more than it matches a typical English-first open source project.

The data flow: Timeline.json in, Travel Journal and MP4 out

The mechanism has three stages, and the middle one is the part people miss.

First, import. You choose a Timeline.json file. The README says the selected JSON file is not copied. Instead, useful journey history is stored in an app-private Travel Journal, and later exports add new detailed route sections. So the app keeps a derived, growing record rather than the raw export.

Second, selection and preview. You choose a saved trip, find one in the Journal, generate a monthly or yearly recap, or enter exact dates. Ranges may cross year boundaries. You then confirm a title, pick a preset or a custom duration from 10 through 300 seconds, and hit Preview. The preview is interactive; the saved video uses the same design with map tiles prepared before rendering. That distinction matters, because a preview that streams tiles and a render that pre-fetches them can diverge in timing even when the design matches.

Third, render. On Android 10 and later the file lands automatically under Movies/Timeline Visualizer; Android 8 and 9 fall back to the system Save As picker. The app reports each stage, an estimated time when enough progress has been measured, and offers a cancel button. Rendering continues if you switch apps or turn the screen off, and on Android 13 or newer notifications let you follow progress outside the app, though video creation continues even if you decline that permission.

The Journal's storage model is the real constraint. The README states it remains only on this device, is excluded from Android backup and device transfer, and is removed by clearing app storage or uninstalling. Import an updated Timeline regularly if you want recent detail preserved. Nothing syncs it.

Installing the Android APK and rendering a first video

There are two install paths. The README points to the Google Play listing, and also to Google Play open testing, which it says needs no application form, invitation, or Google Group membership, though availability depends on country and device. The third path is a direct APK from the repository's latest release.

For the direct APK, download the TimelineVisualizer-*.apk asset on your phone and not the .sha256 checksum file:

# on the phone: download TimelineVisualizer-*.apk from
# https://github.com/mahlernim/google-timeline-visualizer/releases/latest
# then open the downloaded file

If Android blocks the install, the README gives the recovery: allow your browser or file manager to Install unknown apps, retry, then turn the permission off again. A warning is expected for an APK distributed outside Google Play, and future releases install over the current one.

Before the app is useful you need the export, and on Android it does not live in Google Maps. The README is explicit: open Phone Settings, then Location, then Location services, then Timeline, then Export Timeline data and Continue, and save Timeline.json somewhere findable such as Downloads. Labels vary by phone, and the app's Get Timeline file screen repeats these steps and can open Location settings, because Android gives apps no standard link to the Timeline page.

Then, in the app:

# 1. Create video -> choose Timeline.json (stored in the local Travel Journal)
# 2. Pick a saved trip, a monthly/yearly recap, or exact dates
# 3. Confirm the title; preset or custom duration, 10 to 300 seconds
# 4. Preview -> Create video
# 5. Output: Movies/Timeline Visualizer (Android 10+)

The title template persists between runs and supports {year} and {name}. Durations over 60 seconds trigger a rendering-time and storage reminder, which is a fair warning rather than a restriction. After the chosen duration the video adds a 1.5-second ending that zooms out, reveals the complete route, and holds the final overview for half a second. If you cancel, the incomplete output file is removed.

The iPhone web app, and where it stops

The iPhone route is a browser page at ahn-lab.org, not an App Store build. The README's steps are: export from Google Maps under profile picture, Settings, Personal content, Export Timeline data and save Timeline.json in Files; return to the web app and choose Choose Timeline.json; pick a month range or exact dates, a distance unit and camera movement, and confirm the map privacy notice; preview; then select Create MP4.

The limitation is stated in the README and it is a hard one. MP4 creation requires Safari 16.4 or newer with H.264 encoding support, and the tab must stay open while the video is being created. That is a different failure profile from the Android app, which continues rendering with the screen off. On iOS you are holding a tab hostage to an encoder.

Two smaller notes from the same section: the web app can be added to the Home Screen through Safari's Share menu, and a Timeline.json exported on iPhone can also be moved to an Android phone and opened there. The reverse also holds, since the file is the interface.

Restoring a missing Google Maps Timeline is not this app's job

This is the section to read before buying into the marketing image of the project. If older trips vanished after a phone change, a Maps reinstall, or a reset, the README says an encrypted Timeline backup may still exist in Google Maps, and points to the app's Restore Google Maps Timeline link and a restoration guide under docs/restore-google-maps-timeline.md.

But the app does not do the restoring. The README states that Timeline Visualizer cannot access your Google account or the encrypted backup and does not restore it directly. You restore inside Google Maps first, then export a fresh JSON file. Anyone who installs this expecting recovery of deleted history has misread what it is: a renderer for a file you already have.

A second boundary is the Journal. Because it is app-private and excluded from Android backup and device transfer, a new phone means a new Journal. Your MP4s under Movies/Timeline Visualizer survive as ordinary files, and the README describes an Add videos action that imports MP4s made before the library existed, selecting several at once. The library index and thumbnails are local and small, so the videos themselves are the durable artifact.

How it compares with the Python visualizer in the same repository

The most direct alternative is not another company's product. It is visualizer.py, sitting at the repository root next to a requirements.txt that pins numpy>=1.20.0, matplotlib>=3.5.0, pillow>=9.0.0 and python-dateutil>=2.8.0.

pip install -r requirements.txt

That is the whole install story for the script, and the contrast with the Android app is the point. The Python path runs on a desktop with a normal Python environment, which suits anyone who wants to script the process, run it over many exports, or avoid installing an APK on a phone. The Android app trades that for a touch interface, an interactive preview, background rendering, and a video library with thumbnails and an in-app player.

The two share the same input, the Timeline JSON export, and the repository keeps tests/, test-fixtures/ and tools/ alongside both, so the parsing and geometry work is not duplicated by accident. If your goal is a one-off video and you already have Python, the script is the shorter path. If your goal is a recurring monthly recap you will actually watch on the device that recorded it, the app is the one with the preview loop and the cancel button.

Maintenance, licence and the cost of upgrading

The last push to the default branch was on 2026-09-22, and the most recent release, v3.1.0-preview.2, was published the same day. Before it came v3.0.18 on 2026-09-12 and v3.0.17 on 2026-09-09. That cadence, with a preview tag sitting on top of a run of patch releases, tells you the project is being worked on rather than parked. The repository is not archived.

The upgrade cost is low on the Android side because of one README sentence: future releases can be installed over this release. There is no migration step described for the Travel Journal between versions, and no rollback procedure documented either. If a release breaks rendering for you, the README does not describe how to go back to an earlier APK; you would be reinstalling from the releases page yourself. That is a gap worth knowing about before you rely on a preview tag.

The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not advice about your situation; if you plan to redistribute the APK or embed the code, read LICENSE in the repository and, where the stakes are real, take your own legal advice. Note that the licence covers the code, not Google's Timeline data or map tiles, which come with their own terms.

Editorial conclusion

Adopt it if you already export Timeline JSON and want a shareable recap without uploading location history anywhere: the Android app renders locally, and the iPhone web app states that no Timeline file is uploaded. Do not adopt it if you expect it to recover a missing Google Maps Timeline, because the README says it cannot access your Google account or the encrypted backup and does not restore it directly. Before installing, verify three things: that your phone runs Android 8.0 or newer, that you can reach Location, Location services, Timeline in the phone Settings app to produce Timeline.json, and that the APK you download comes from the repository's latest release assets rather than a mirror, since the README warns only to download it there.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mahlernim/google-timeline-visualizer on GitHub
4. README
5. Releases