Product Introduction
Definition: google-timeline-visualizer is an open-source, cross-platform geospatial data visualization tool that converts raw Google Location History (Timeline) JSON exports into animated, interactive travel map videos. It is a specialized location-data-to-video pipeline that processes GPS coordinates, semantic segments, and activity/latLng records through a rendering engine to produce MP4 output. The product exists in three distribution models: a native Android application, a server-side web app optimized for iPhone Safari (16.4+ with H.264 encoding), and a legacy desktop Python script. The core engine automates the entire workflow from JSON ingestion, coordinate parsing, and route geometry construction to camera path animation and tile-based map rendering.
Core Value Proposition: The tool solves the fundamental problem of data lock-in: Google exports Timeline information as a hard-to-read, deeply nested JSON file that offers no visual or narrative value to the average user. google-timeline-visualizer transforms that raw location history into an engaging, shareable MP4 travel documentary, allowing users to visually recap their year, analyze travel patterns, and preserve memories in a cinematic format. It does this with a strict privacy-first architecture—no Google sign-in, no location permissions, and no server-side processing of personal data.
Main Features
1. Android Native App with Direct APK Distribution: The Android application (v2.2.4) is distributed directly via GitHub Releases, bypassing the Google Play Store. It requires Android 8.0 or newer and handles the entire video creation pipeline on-device. The app's "Get Timeline file" helper guides users to the phone's Settings → Location → Location services → Timeline → Export Timeline data flow, since Android's export path differs from iOS. The app automatically saves completed videos to Movies/Timeline Visualizer on Android 10+ and uses the system Save As picker for Android 8–9. The app maintains a local index of completed videos in a "My videos" library, storing only a small metadata index and a deterministic thumbnail derived from the final journey overview frame—not the underlying Timeline data. A "Delete video" function permanently removes files when the storage provider permits it, while "Remove from list" leaves the MP4 untouched.
2. iPhone Web App (No Installation Required): The iPhone version runs entirely in Safari with no App Store installation and no file upload to external servers. Users export Timeline.json from Google Maps (profile picture → Settings → Personal content → Export Timeline data) and save it in Files. The web app reads the local file, processes it client-side, and renders an MP4 using Safari's native H.264 encoding API (requires Safari 16.4+). The app can be added to the Home Screen via Safari's Share menu. The rendering requires the tab to remain open, and the entire process is completed locally on the device—a significant departure from cloud-based video renderers.
3. Multi-Format Timeline Parsing Engine:
The parser supports current Android and iOS direct-array Timeline exports, legacy {"semanticSegments": [...]} structures, and an optional raw location fallback with local noise reduction. It handles multiple coordinate formats including String, latLng, degree, geo:, and E7 (×10⁷) encoded coordinates, ensuring compatibility across different export versions and device types. The engine also correctly processes routes that cross the international date line, a common source of visualization errors in GPS tools.
4. Great-Circle Path Interpolation: Sparse routes—such as long-haul flights with limited coordinate density—are interpolated along great-circle paths rather than treated as straight lines or skipped entirely. This means the animated camera follows the actual geodesic curve between waypoints, producing smooth, realistic travel sequences instead of jarring jumps across continents. This is particularly critical for intercontinental flights where raw Google Timeline data may contain only departure and arrival coordinates.
5. Camera Movement System with Three Modes: Users can select between three camera behavior profiles. Steady camera (default) maintains a stable view with gradual transitions, ideal for overview presentations. Fixed camera keeps a single constant zoom level throughout the journey, providing a consistent geographic context. Dynamic camera actively follows local movement with more frequent zoom adjustments, suited for detailed urban travel sequences. A dedicated "stable central area" logic allows the marker to move within a defined zone before triggering camera movement, reducing distracting back-and-forth panning on daily commutes while preserving all original Timeline points.
6. Long-Trip Compression and GPS Outlier Filtering: The "Long-trip compression" feature separates animation timing from route geometry, allowing entire years of location data to fit within a 10–300 second journey duration without altering the underlying path. The "Balanced" mode is the default; users can also choose fixed or dynamic compression levels. Additionally, the "Conservative GPS outlier filter" (default enabled) detects and removes isolated, implausible out-and-back coordinates—a common artifact of GPS drift in urban canyons or tunnels—and reports the number of ignored points. Users can disable the filter to use every location from the exported file. All processing is non-destructive; the original JSON file remains unchanged.
7. Multi-Language Localization (9 Languages): The user interface supports English, Korean, Japanese, Simplified Chinese, Traditional Chinese, Spanish, French, German, and Brazilian Portuguese. Users can select a language explicitly in Settings or default to the system locale. This broad localization reflects the global user base of Google Timeline and makes the tool accessible to non-English-speaking travelers.
8. Customizable Video Output Presets:
Video format settings offer multiple resolution presets: square 480p, 720p, and 1080p; portrait 1080×1920 for mobile-first sharing (Stories/Shorts/TikTok); and landscape 1920×1080 for YouTube or television viewing. Users select journey durations from 10 to 300 seconds, with durations over 60 seconds triggering a clear rendering-time and storage reminder. Title templates support {year} and {name} placeholders, and the template is saved automatically for subsequent renders. The final video appends a 1.5-second ending sequence that zooms out, reveals the complete route, and holds the final overview for half a second—providing a satisfying summary frame.
9. Desktop Python Renderer (Legacy):
A desktop Python version (visualizer.py) remains available for power users. It requires Python 3.9+, FFmpeg, and the dependencies listed in requirements.txt. The CLI accepts --input, --year, --camera-movement, --long-trip-compression, and --output flags, enabling scripted and batch processing of travel videos. This is the original generator that predates the mobile apps and remains valuable for automated workflows.
Problems Solved
1. Pain Point: Inaccessible Raw Location Data Google's Location History export is a multi-megabyte JSON file with deeply nested objects, timestamps, latitude/longitude coordinates (in E7 format), and semantic segment metadata. The structure is unintelligible to non-developers, and even engineers find it time-consuming to parse and visualize. google-timeline-visualizer eliminates this barrier by abstracting the entire parsing, filtering, and rendering pipeline behind a simple "Select file → Create video" interface. This directly addresses the "dark data" problem—location history collected continuously by Google that users cannot practically use or understand.
2. Pain Point: Privacy Anxiety Around Location Data Unlike third-party services that require uploading your Timeline to cloud servers for processing, google-timeline-visualizer is explicitly designed with a zero-upload architecture. There is no Google sign-in, no location permission request, no analytics SDK, and no broad storage permission. The Timeline JSON is never transmitted. The only network request is to CARTO's tile server (for OpenStreetMap-based basemap tiles), which is disclosed before the first Timeline load with a clear privacy explanation. This makes the tool uniquely trustworthy for security-conscious users who want to explore their location data without exposing it to additional third parties.
3. Pain Point: Recovering Lost Travel History After Device Migration Users who change phones, reinstall Google Maps, or reset devices often discover older Timeline trips have vanished from their Timeline view. The app provides a direct "Restore Google Maps Timeline" link and guidance for Google's encrypted backup restoration flow. While Timeline Visualizer cannot access a Google account or encrypted backup directly, it streamlines the recovery process by directing users to the correct restoration sequence in Google Maps, then accepting the re-exported JSON. This turns a confusing data-loss situation into a recoverable workflow.
4. Target Audience:
- Frequent Travelers & Digital Nomads: Individuals who want an annual travel recap to share on social media or preserve as a personal memory artifact.
- Lifestyle Journalers & Memory Keepers: Users who document their lives through location data and want a cinematic, navigable record of where they've been.
- Data Privacy Advocates: Privacy-conscious users who refuse to upload personal location history to untrusted third-party services.
- Non-Technical Google Users: People who receive an "Export your data" prompt from Google Takeout but cannot interpret or visualize the resulting JSON files.
- Android & iOS Power Users: Tech-savvy consumers who want native, on-device conversion without cloud dependencies.
- Data Scientists & GIS Hobbyists: Technical users who leverage the Python CLI to batch-process location history for personal analytics or route visualization experiments.
5. Use Cases:
- Annual Travel Recap Videos: Generate a 60-second MP4 summarizing a full year of travel, with a camera that smoothly flies between cities. Output in 1080×1080 square for Instagram or 1920×1080 for YouTube.
- Trip-Specific Montages: Select exact date ranges (e.g., a 5-day vacation) to create a focused, short-form video with the Dynamic camera mode that highlights walking paths, vehicle routes, and stopovers.
- Restored Timeline Verification: After running Google's encrypted backup restoration, export the new JSON and preview the journey to verify all historical trips were recovered correctly.
- Comprehensive Travel Logging: Use the Steady camera mode with 300-second durations to create up to 5-minute documentary-style videos of year-long worldwide travel, including long-haul flights with great-circle interpolation.
- Social Media Content Creation: Export portrait 1080×1920 videos for TikTok/Instagram Reels/YouTube Shorts, leveraging the template system with
{year}and{name}placeholders for serial content production. - Personal Data Audit: Run the Conservative GPS outlier filter and review the reported ignored-point count to identify areas of poor GPS coverage in daily life.
Unique Advantages
1. Differentiation from Cloud-Based Timeline Visualizers: Most competing services (e.g., web-based Google Takeout visualizers, third-party "location history map" tools) require users to upload their JSON to a server for processing. google-timeline-visualizer is unique in that its Android and iOS implementations process everything locally on the device. This is a decisive advantage for privacy-sensitive users and also means the tool works offline (after the map tiles are cached), making it functional in low-connectivity environments like airplanes or remote travel destinations. Furthermore, the desktop version offers direct CLI processing for scripted pipelines, which cloud-based alternatives cannot match. The dual approach—native app plus open-source Python fallback—gives it a level of tooling depth that consumer-focused competitors lack.
2. Key Innovation: The Automated Cinematography Layer: Rather than merely plotting markers on a static map, the tool incorporates a deterministic camera control system that introduces video-cinematography techniques—camera easing, stable central dead zones, zoom-out endings, and route-revealing final frames—all generated from raw GPS data without user video-editing skills. This is a substantial technical achievement because translating sparse timestamped coordinates into natural-looking camera motion, without jarring jumps, requires careful handling of coordinate systems, time-based interpolation, and map-projection math. The addition of great-circle interpolation and international date-line handling further elevates the technical rigor, ensuring the generated video is not only watchable but genuinely cinematic, which is remarkably rare in open-source location visualization tools.
3. Differentiated Platform Strategy: The product deliberately avoids the Google Play Store (due to distribution restrictions for APKs and Google's policies) in favor of direct GitHub Releases, ensuring users are not subject to Play Store installation restrictions or review delays. By simultaneously supporting an iPhone web app, Android APK, and Python script, it covers a broader OS landscape than most personal open-source projects. This multi-platform architecture—a single rendering engine adapted to three runtimes—is an engineering decision that maximizes reach while preserving the privacy promise.
4. Key Innovation: Deterministic Thumbnail Generation: For the "My videos" library, the app generates a deterministic thumbnail from the final journey overview frame. This ensures every entry in the library has a meaningful, stable preview image without storing any additional data in the app index—a small but significant detail that keeps the app lightweight and privacy-conscious while delivering a polished video-library experience.
5. Transparent Render Pipeline: Unlike black-box video generators, the tool provides visible stage-based progress indicators, an estimated time-remaining calculation (once enough progress has been measured), and a cancellation mechanism that removes incomplete outputs. Users can switch apps or turn off the screen while rendering continues on Android, and notifications (Android 13+) provide progress updates outside the app. This transparency gives users control over long renders of dense Timeline datasets and builds trust in the tool's reliability.
Frequently Asked Questions (FAQ)
1. Is my Google Location History Timeline data uploaded or shared when I use google-timeline-visualizer? No. The application is designed with a zero-upload philosophy. The Timeline JSON you select is processed entirely on your device—whether that is your Android phone, iPhone (via the Safari web app), or desktop (via the Python script). The only external network request is to CARTO for basemap tiles based on OpenStreetMap data; this request corresponds only to the visible map areas and does not include any Timeline information. The app does not use analytics, does not require account access, and does not request broad storage permissions. On iPhone, the entire MP4 creation process happens client-side in Safari and requires H.264 encoding support (Safari 16.4 or newer).
2. What file formats and export structures does this tool support?
The parser accepts modern Google Timeline direct-array exports (current Android/iOS format), legacy exports that use the {"semanticSegments": [...]} structure, and offers an optional raw location fallback with local noise reduction for malformed or older JSON files. It handles String coordinates, latLng objects, degree values, geo: URI strings, and E7 integer coordinates. It also correctly handles route geometry that crosses the international date line, preventing map line artifacts in the Pacific region.
3. Can I use this tool to create videos of a specific trip rather than the entire year?
Yes. The "Exact dates" mode is explicitly designed for short-duration trips spanning only a few days. Users select a month range or precise date boundaries in the Create video screen, and the tool renders only that time window. The default selection is the latest full year, but ranges may cross year boundaries, so a December-to-January trip can be captured as a single continuous video. The camera movement mode, journey duration (10–300 seconds), and video resolution preset are all configurable for each render.
4. Why does my Android phone say the app is "blocked" when installing the APK?
Android displays a warning when installing apps from outside the Google Play Store. Since this app is distributed directly from GitHub Releases, you must grant "Install unknown apps" permission to your browser or file manager. The installation screen provides a direct "Settings" button to enable this. The warning is an expected part of distributing an APK directly, and you can revoke the permission after installation is complete. Google Play Protect may also display a warning; this is a generic alert for directly distributed APKs, not an indication of malicious code. Always download the APK only from this repository's official Releases page (latest version: v2.2.4).
5. Does google-timeline-visualizer require a Google account or Google Maps app to function?
No. The tool cannot access your Google account, cannot read Timeline data from the cloud, and does not integrate with Google's API services. You must manually export the Timeline.json file first—via Phone Settings on Android, or Google Maps settings on iPhone—and then provide that file through the app's file picker. It also cannot directly restore a missing or broken Google Maps Timeline; the restoration must be done inside Google Maps using Google's encrypted backup system, after which you export a fresh JSON for the visualizer.
6. What technical requirements are needed to run the video creation feature on an iPhone?
The iPhone web app requires Safari 16.4 or newer, specifically because MP4 creation relies on Safari's native H.264 video encoding capabilities. The tab must remain open throughout the rendering process, and the device screen should not be locked in a way that suspends browser background work. There is no app to install, no App Store listing, and no Timeline file upload. Users are advised to keep the tab active and add the web app to the Home Screen for a more native experience.
