DOCSEARCHbyAlgolia
Submit Docs

GeoPulse Documentation

repository·main·Indexed 23 days ago

https://github.com/tess1o/geopulse

An open-source, privacy-first, self-hosted alternative to Google Timeline. GeoPulse processes GPS data from sources like OwnTracks, Overland, and Google Takeout to create a searchable timeline of movements. It features integrations with Immich and Memos, AI-powered location insights, and supports deployment via Docker Compose or Helm charts for Kubernetes.

Tokens
110.4K
Snippets
174
Records
480
Agent score
78%

What's inside GeoPulse

  1. Overview of GeoPulse Helm Chart features

    main

    The GeoPulse Helm chart provides a production-ready full-stack deployment including:

    • Full Stack: Backend (Java/Quarkus in Native mode), Frontend (Vue.js), and PostgreSQL with PostGIS.
    • Optional MQTT: Conditional deployment of a Mosquitto MQTT broker.
    • Production Readiness: Includes health checks, resource limits, and persistent storage.
    • Security: Automatic JWT key generation and secrets management.
    • Connectivity: Ingress support (optional) and High Availability support via replicas and pod disruption budgets.

  2. Overview of GeoPulse features

    main

    GeoPulse is a privacy-first, self-hosted alternative to Google Timeline that transforms raw GPS data into a searchable timeline of stays, trips, and movement patterns.

    Core Capabilities:

    • Timeline & Analysis: Automatically detects stays, trips, and data gaps with configurable sensitivity. Includes deep insights into distance, frequency, and movement patterns.
    • Integrations:
      • Immich: Displays photos from your library on the map timeline.
      • Memos: Shows timestamped notes alongside your timeline.
      • Weather: Provides current weather enrichment for trips and stays (historical backfill is admin opt-in).
    • Data Sources: Supports real-time tracking from OwnTracks (HTTP/MQTT), Overland, GPSLogger, Home Assistant, Traccar, Dawarich, and Colota. Supports bulk import from Google Timeline, GPX, GeoJSON, OwnTracks exports, and CSV.
    • Privacy & Sharing: Features a 'Friends System' for per-user visibility, guest access with password protection, and multi-user roles with OIDC/SSO support.
    • AI Insights: Supports OpenAI-compatible keys for natural-language queries about your location data.

  3. Overview of GeoPulse features and capabilities

    main

    GeoPulse is a self-hosted platform designed to transform raw GPS data into actionable insights. It provides a centralized hub for location tracking, visualization, and analysis.

    Key capabilities include:

    • GPS Data Integration: Supports multiple sources via HTTP, MQTT, or file imports (GPX, GeoJSON, or Google Timeline). It automatically merges and cleans incoming data.
    • Timeline and Maps: Visualizes movement history through categorized stays, trips, and data gaps. It integrates with Immich to display photos directly on the map.
    • Analytics: Provides travel statistics including total distance, visited countries/cities, and AI-powered journey insights.
    • AI Assistant: Allows natural-language querying of travel patterns using any OpenAI-compatible API.
    • Sharing and Privacy: Enables secure sharing of real-time locations or timelines via password-protected and time-limited links.
    • Personalization: Per-user customization for map tiles, favorite places, time zones, measurement units, and AI preferences.

  4. Summary of Travel Classification features

    main

    Travel classification automatically identifies travel modes based on GPS speed data using the following mechanisms:

    • Configurable trip types:
      • WALK (always available)
      • CAR, BICYCLE, RUNNING, TRAIN, FLIGHT (optional)
      • UNKNOWN (fallback type)
    • Smart algorithms: Includes GPS noise detection, reliability validation, and special case handling.
    • Manual control: Users can override movement type per trip and reset to automatic at any time.
    • Customization: Speed thresholds can be adjusted to match specific travel patterns.
    • Automatic updates: Enabling or disabling trip types triggers instant classification updates.

  5. View trip photos via Immich integration

    main

    If the Immich integration is enabled and the trip's date range contains photos, the Trip Workspace provides additional spatial and temporal context:

    • Trip Photos: Photos can be displayed within the workspace context.
    • Map Photo Layer: A dedicated layer can be used for spatial review of where photos were taken.

    Note: If Immich is disabled, all photo-specific UI elements are hidden.

  6. Use dynamic setup instructions for active sources

    main

    GeoPulse provides a dynamic Setup Instructions section located below your configured sources. This section automatically generates step-by-step guides for every currently active source type you have added.

    These instructions include the specific URLs, data formats, and authentication details required to complete the integration within your third-party application.

  7. Use Favorite Areas to prevent fragmented stays

    main

    Favorite Areas allow the system to treat large venues (like malls or campuses) as single locations even if movement between points exceeds the Stay Detection Radius.

    Logic: When a new point is outside the stay radius, the system checks if the current centroid and the new point are both within the same Favorite Area. If they are, the stay continues instead of transitioning to IN_TRIP.

    Example:

    • Without Favorite Area: Walking between two shops in a mall (100m apart) results in two separate stays.
    • With Mall as Favorite Area: Walking between those same shops results in one continuous stay at the "Shopping Mall".

  8. Understand the GeoPulse settings hierarchy

    main

    GeoPulse applies settings based on the following precedence order (from highest to lowest priority):

    1. Database (Custom): Settings modified via the Admin UI. These override all other configurations.
    2. Environment Variables: Default configuration provided during deployment.
    3. Application Defaults: Built-in system defaults.

    In the Admin UI, custom values can be reverted to their original defaults using the Reset button.

  10. Understand how measurement units affect data

    main

    GeoPulse uses a display-only approach for measurement units.

    • Data Storage: All GPS data is always stored in meters in the database. Changing the measurement unit does not change how data is saved or processed.
    • Display Logic: The setting only affects the visual representation of values (e.g., converting meters to feet/miles or km/h to mph) in the UI.
    • Safety: Switching units is safe; no data is lost or recalculated.

  11. Understand Geofence Event Delivery and Status

    main

    Apprise delivery is an additional feature and does not replace in-app storage; every geofence event is always persisted in-app.

    Delivery status is tracked via metadata on the event records using the following states:

    • PENDING: Notification is queued.
    • SENT: Notification was successfully delivered to Apprise.
    • FAILED: Delivery attempt failed (check Apprise logs).
    • SKIPPED: External routing was missing, disabled, or the template path was non-deliverable.

  12. Understand GeoPulse Import Performance and Limits

    main

    GeoPulse is designed to handle very large datasets (up to 10GB by default) using streaming parsers and chunked uploads.

    Key Performance Features

    • Streaming Parsers: Data is processed in chunks rather than being loaded entirely into memory, ensuring low memory usage.
    • Chunked Uploads: Files larger than 80MB are automatically split into 50MB chunks on the frontend. This bypasses common proxy/CDN limits (like Cloudflare's 100MB limit) and allows for reliable uploads of massive files.
    • Automatic Timeline Generation: Once GPS data is imported (at ~70% progress), GeoPulse automatically begins generating timeline items (trips and stays) in the background.

    Configuration Limits

    • Max File Size: The default maximum is 10GB, configurable via GEOPULSE_IMPORT_MAX_FILE_SIZE_GB.
    • Drop Folder Size Cap: For automated drop folder imports, there is a specific cap for GeoPulse ZIP files (default 200MB), controlled by GEOPULSE_IMPORT_DROP_FOLDER_GEOPULSE_MAX_SIZE_MB.