whereami

README

Where Am I

A lightweight desktop waypoint and GPX viewer for exploring and managing location data.

Features

• Interactive vector map: Explore the OpenFreeMap basemap with resolution-independent vector rendering, mouse navigation, and touch gestures
• Bookmarks: Add, rename, tag, and delete saved locations
• GPX import: Recursively import GPX files from a selected directory
• Search: Search local waypoints and remote Nominatim geocoding results
• Filters: Show bookmarks only, filter by tag, or select an inclusive UTC date range
• Timeline: Travel through significant recorded locations on an animated offline-resolved map
• Themes: Six runtime-selectable color themes
• Keyboard shortcuts: Open the in-app shortcut list with Ctrl+? or Ctrl+/

[!WARNING] WhereAmI is beta-quality software. It has been tested in a Fedora Workstation environment only.

Installation

From a Release

Download the Flatpak bundle from the releases page and install it:

flatpak install --user io.github.rubiojr.whereami.flatpak

Packaging lives in whereami-flatpak.

From Source

Requirements: Go 1.25 or newer, Qt 6.5 or newer, GCC, and miqt-rcc. The OpenFreeMap basemap also requires the MapLibre Native QtLocation provider; without it, the application remains usable but shows an overlay-only map. The Flatpak builds and bundles the matching provider.

Administrative place timelines use an optional local Xiangshan generation. See docs/GEODATA.md for make geodata-build, make geodata-dist, and the isolated make geodata-run-local workflow.

git clone https://github.com/rubiojr/whereami.git
cd whereami
make build
bin/whereami

See BUILD.md for detailed build instructions.

Use Case

WhereAmI can display location history exported as GPX. One example is combining it with hass2geo and the Home Assistant companion app to keep location history in a private Home Assistant instance and import the resulting GPX directory.

Usage

• Add a bookmark: Right-click the map. To reuse a selected or searched location, press Ctrl+Enter or Ctrl+Return.
• Import GPX: Select a directory with the folder button in the toolbar. Import scans recursively, preserves relative paths, replaces changed files atomically, and reports unsupported or invalid files separately.
• Search: Press Ctrl+F and use the search box.
• Filter by date: Use the calendar button in the toolbar to choose a day, range, or UTC date preset. Click the highlighted button again to clear the filter.
• Explore a year: Use the timeline button to open the current year's timeline, then move through older or newer locations. Consecutive movement below 100 meters is grouped into one stop.
• Navigate: Drag to pan, use the mouse wheel to zoom, or use touch pinch gestures.
• Themes: Start the application with --theme=<variant>, where the variant is orange, green, purple, adwaita-dark, nord-polar, or nord-frost. The default is nord-polar.
• All shortcuts: Press Ctrl+? or Ctrl+/.

Command-Line Options

-cache-dir string
      custom cache directory (overrides XDG_CACHE_HOME)
-config-dir string
      custom config directory (overrides XDG_CONFIG_HOME)
-data-dir string
      custom data directory (overrides XDG_DATA_HOME)
-debug
      enable debug logging
-theme string
      theme variant (orange|green|purple|adwaita-dark|nord-polar|nord-frost)

Storage

On Linux, the defaults are:

• Data: ${XDG_DATA_HOME:-$HOME/.local/share}/whereami/
• Cache: ${XDG_CACHE_HOME:-$HOME/.cache}/whereami/
• Configuration: ${XDG_CONFIG_HOME:-$HOME/.config}/whereami/

The data directory contains bookmarks, imported GPX files, tags, and search history. The cache directory contains geocoding caches, a rebuildable observation index, dataset-versioned administrative resolutions used by timelines, and the maplibre/ map cache. The three command-line directory options override these locations.

The map cache stores vector tiles, styles, glyphs, and sprites in a single database with a 256 MB budget, so areas already viewed keep rendering while offline.

License

The application source is under the MIT License. See LICENSE. Flatpak releases also bundle MapLibre Native Qt under its upstream licenses.

Contributing

See the project guidance in .rules.