OpenSAK

01Installation

Linux (Recommended: Automatic Installer)

Paste this single command into a terminal — it handles everything automatically:

curl -fsSL https://raw.githubusercontent.com/AgreeDK/OpenSAK/main/scripts/install-opensak.sh | bash

The installer will check dependencies, clone the repository to ~/opensak, create a virtual environment, and add an application menu entry.

Linux — AppImage

chmod +x OpenSAK-*.AppImage
./OpenSAK-*.AppImage

Linux — Manual

sudo apt install git python3 python3-venv python3-pip libxcb-cursor0
git clone https://github.com/AgreeDK/opensak.git ~/opensak
cd ~/opensak
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py

Windows

Download OpenSAK-Windows.zip from the Releases page, unzip, and run OpenSAK.exe. No Python installation required.

macOS

Download the correct .dmg for your Mac from the Releases page:

Open the .dmg and drag OpenSAK to Applications. On first launch, right-click → Open to bypass Gatekeeper.

System Requirements

02First Launch & Setup

When OpenSAK opens for the first time, a welcome dialog will offer to open Settings. It is recommended to do this now.

Setting Your Home Point

The home point is your reference coordinate for distance calculations and map centering. Go to Settings → Settings… (Ctrl+,), then in the User Locations section:

1. Enter a name (e.g. Home).
2. Enter your coordinates in any supported format (e.g. N55 47.250 E012 25.000, decimal degrees, or DMS).
3. Click Save point. The point appears in the table above.
4. Click ★ Activate to make it the active home point.

Setting Your Geocaching Username

Go to Settings → Geocaching.com tab. Enter your Geocaching.com username. This is used to identify your own caches in the list and for FTF (First to Find) detection in your logs.

03Importing Caches

OpenSAK works with GPX files and Pocket Query ZIP files — the same files you already download from Geocaching.com. No special export step is needed.

Downloading a Pocket Query (Recommended)

1. Log in to geocaching.com.
2. Go to Play → Pocket Queries.
3. Run or create a Pocket Query for your area.
4. Download the .zip file — do not unzip it.

Importing into OpenSAK

There are three ways to import:

• Menu: File → Import GPX / PQ zip… (Ctrl+I)
• Toolbar: Click the Import button
• Drag & drop: Drag one or more .gpx, .zip, or .loc files directly onto the OpenSAK window

In the Import dialog you can add multiple files at once and choose which database to import into. Click Start import. After import, a summary shows new caches, updated caches, and any errors.

Auto-geocoding

After import, OpenSAK automatically runs an offline reverse-geocode pass to fill in Country, State/Region, and County for any caches that are missing these fields. This works with no internet connection.

Supported Formats

04Main Window Layout

The window is divided into three main areas, all resizable by dragging the dividers:

• Cache List (top) — full-width table of all caches matching the active filter
• Cache Detail Panel (bottom-left) — full description, hint, attributes, and logs for the selected cache
• Map (bottom-right) — interactive OpenStreetMap with colour-coded cache pins

05Cache List

Columns

The cache list shows up to 17+ configurable columns. Choose which ones are visible via View → Choose columns… Click any column header to sort — click again to reverse the sort order. The sort is saved per database.

Clicking a Cache

Clicking a row selects the cache: the detail panel updates to show its full information, and the map pans to its pin.

Right-Click Context Menu

Right-clicking a cache in the list shows:

• Open on geocaching.com — opens the cache page in your browser
• Copy coordinates — copies coordinates to clipboard
• Mark as found / unfound
• Toggle flag 🚩 — flag caches for batch operations
• Edit cache… — opens the edit dialog
• Add corrected coordinates… — enter solved coordinates for mystery caches
• Edit corrected coordinates… / Clear corrected coordinates

Sortable Columns (examples)

06Cache Detail Panel

The bottom-left panel shows all information for the currently selected cache.

Tabs

• Description — full HTML cache description as published on geocaching.com
• Hint — encrypted hint; click anywhere on the hint text to toggle ROT13 decoding
• Logs — recent logs from all finders; includes a search box to find specific entries
• Attributes — all Groundspeak attributes set on the cache (dogs, parking, etc.)

Clickable Elements

• GC code — click to open the cache page on geocaching.com
• Coordinates — click to open in your chosen map app (Google Maps or OpenStreetMap)
• Corrected coordinates — if set, shown with an ✏️ edit button and a 🗑 clear button; click the coordinates to open in map app

07Map

The map uses OpenStreetMap tiles via Leaflet.js. It always shows the caches currently visible in the cache list (respecting the active filter).

Pin Colors

Interactions

• Click a pin to select that cache — the detail panel and list row update accordingly.
• Pins cluster automatically when zoomed out; click a cluster to zoom in.
• Corrected coordinates are shown as a separate pin (📍) linked to the original.
• Use the ⌂ button in the toolbar to pan the map to your active home point.

08Info Bar

The narrow bar between the cache list and the detail/map panels gives a quick status overview at all times.

09Search & Quick Filters

Search Bar

The search toolbar sits below the main toolbar and is always visible. Two independent fields:

• GC: search by GC code (partial match, case-insensitive)
• Name: search by cache name (partial match, case-insensitive)

The list updates live as you type. Clearing a field immediately resets that search.

Quick Filter Dropdown (in menu bar)

A fast single-click filter in the menu bar:

10Filter Dialog

Open with View → Set filter… or Ctrl+F, or click the 🔍 Filter button in the toolbar.

AND / OR Logic

All filters default to AND mode — a cache must pass every active filter to appear. Switch the group to OR to show caches matching any filter. Groups can be nested for complex conditions.

Filter Tabs

The filter dialog has four tabs:

• General — type, container, difficulty, terrain, distance, found/not found, availability, country, state, county, name, GC code, placed by, owner, trackables, premium, corrected coords
• Dates — filter by found date, hidden date, or last log date
• Attributes — all ~70 standard Groundspeak attributes, with positive/negative matching
• Other — user flag, DNF flag, FTF flag, favorite points range
• Where — raw SQL WHERE clause against the caches table (advanced)

Clearing the Filter

Click the red ✕ button in the toolbar, or go to View → Clear filter. The button turns grey when no filter is active.

11All Filter Types

Common Filter Recipes

12Filter Profiles

Save and reload filter combinations with a single click.

Saving a Profile

1. Open the filter dialog and configure your filters.
2. Click Save profile.
3. Enter a name (e.g. Easy day trip) and confirm.

Loading a Profile

Either open the filter dialog and select the profile from the dropdown, or use the filter profile dropdown in the toolbar — selecting a profile there applies it immediately without opening the dialog.

Profile files are stored at:

• Linux/macOS: ~/.local/share/opensak/filters/
• Windows: %APPDATA%\opensak\filters\

13Databases

OpenSAK supports multiple separate SQLite databases. Each database has its own cache list, home point, and filter profile history.

Managing Databases

Open the Database Manager with File → Manage databases… (Ctrl+D) or click the Manage databases button in the toolbar.

Creating a New Database

1. Click New Database.
2. Choose a location and filename.
3. The database is created and becomes the active database.

Switching Databases

Either double-click a database in the manager, or use the database dropdown in the toolbar to switch instantly without opening the dialog.

Useful Multi-Database Patterns

14Waypoints & Manual Caches

You can manually add, edit, and delete caches in your database — useful for custom waypoints or entries not available via GPX import.

Adding a Cache Manually

Go to Waypoint → Add cache… (Ctrl+N). Fill in the GC code, name, type, coordinates, and other fields, then click Save. The entry is assigned an auto-generated CWxxx code if you leave the GC code blank.

Editing a Cache

Select a cache and use Waypoint → Edit cache… (Ctrl+E), or right-click → Edit cache…

Deleting a Cache

Select a cache and press Delete, or go to Waypoint → Delete cache… A confirmation dialog prevents accidental deletion.

15Corrected Coordinates

For mystery and puzzle caches, store the solved final coordinates separately from the listed coordinates. Corrected coordinates are used for GPS export, trip planning, and map display.

Adding Corrected Coordinates

Right-click the cache in the list → 📍 Add corrected coordinates… (or click the Add corrected coordinates button in the detail panel).

Enter the solved coordinates in any supported format (DMM, DMS, or decimal degrees). The original coordinates are preserved and shown alongside the corrected ones.

Editing or Clearing

Right-click → 📍 Edit corrected coordinates… or ✕ Clear corrected coordinates. The ✏️ and 🗑 buttons in the detail panel also work.

16Marking Caches as Found

Marking a Single Cache

Right-click the cache in the list → Mark as found (or Mark as unfound to reverse it). The found date is set to today.

Auto-detection During Import

When importing a Pocket Query, OpenSAK automatically detects your finds by looking for your own log entries in the imported GPX data. The found status and found date are set without any extra step — as long as your Geocaching.com username is set in Settings.

FTF Detection

First to Find status is also detected automatically during import: OpenSAK scans your own log entries for FTF keyword patterns (e.g. "FTF", "First to Find", "First Find") and sets the FTF flag accordingly.

17Updating Finds from "My Finds"

For the most accurate found status, use a My Finds Pocket Query. This works even for caches found before you started using OpenSAK.

1. On geocaching.com, go to Play → Pocket Queries and download your My Finds zip.
2. Create a dedicated database in OpenSAK called My Finds and import the zip into it.
3. Switch back to your main database.
4. Go to Settings → Update finds from reference database…
5. Select the My Finds database as the reference.
6. OpenSAK matches GC codes and marks all matching caches as found.

18Flags

The 🚩 flag is a personal marker you can set on any cache. Flags are saved in your local database and not shared or affected by imports.

Toggling a Flag

Right-click a cache → Toggle flag 🚩, or click in the 🚩 column directly.

Flag Count

The info bar shows the current count of flagged caches in the active filter (🚩 = N). The status bar also shows a count when you toggle a flag.

Batch Operations on Flagged Caches

• Waypoint → 🚩 Delete flagged caches… — delete all flagged caches in the current filter (with confirmation)
• Waypoint → Clear all flags — remove all flags from the entire active database

You can also filter for flagged/unflagged caches using the User flag filter in the filter dialog.

19Deleting Caches

Three delete operations are available under the Waypoint menu:

20Send to GPS

Export the currently filtered caches directly to a Garmin GPS device or save them to a file.

Open with GPS → Send to GPS… (Ctrl+G) or the 📤 button in the toolbar.

Sending to a Garmin Device

1. Connect your Garmin device via USB.
2. Select Send directly to GPS device.
3. Click 🔍 Scan to detect mounted Garmin devices.
4. Select your device from the list.
5. Click Send.

Caches are written to the Garmin/GPX/ folder on the device as a standard GPX file.

Saving as a GPX File

Select Save as GPX file, choose a location, and click Send. This is useful for devices that are not automatically detected, or for copying to another location.

Export Options

• Choose how many logs per cache to include
• Corrected coordinates are exported as the primary coordinate (original stored separately)

21File Export (GPX / LOC / GGZ)

Export your filtered caches to standard geocaching file formats via File → Export:

All exports use the caches currently visible in the list (respecting the active filter).

22Export to Google Maps (KML)

Export your filtered caches as a KML file for viewing in Google Maps.

Go to File → Export → Export to Google Maps (KML)…

Options

• Include custom waypoints (parking spots, stages, finals)
• Include caches you have already found

Importing into Google Maps

1. Go to maps.google.com/d
2. Create a new map
3. Click Import layer and upload the KML file

23Trip Planner

Plan a geocaching outing by selecting the best caches from your current database. Open with GPS → Trip Planner (Ctrl+T) or the 🗺️ button in the toolbar.

Radius Mode

Select caches within a circle around your home point:

• Set the number of caches for the trip
• Set a maximum radius (or 0 for no limit)
• Sort by distance, difficulty, terrain, placement date, or name
• Optionally filter to unfound and/or available caches only

Route Mode (A → B → … )

Select caches along a driving route:

• Add up to several waypoints (hotel, rest stop, destination)
• Add points from your saved home points
• Set a corridor width (max distance from the route)
• Caches are sorted in driving order along the route

Exporting the Trip

From the Trip Planner you can:

• 📤 Send to GPS… — directly to a connected Garmin device
• 💾 Save as GPX file… — save the trip as a GPX
• 🗺️ Show on map — preview selected caches on an interactive map
• 🗄️ Save to database… — save the trip caches to a new or existing OpenSAK database

24Coordinate Converter

Open with Tools → Coordinate Converter (Ctrl+K).

Convert between coordinate formats: Degrees-Minutes-Seconds (DMS), Decimal Minutes (DMM), and Decimal Degrees (DD). If a cache is selected, its coordinates are pre-filled.

Paste any coordinate string in any format — the converter detects the format automatically and displays the equivalent in all three formats.

25Coordinate Projection

Open with Tools → Coordinate Projection (Ctrl+P).

Calculate a new coordinate by projecting from a known point at a specific bearing and distance. Useful for multi-caches where a stage gives you a bearing and distance to the next point.

• Enter or paste the starting coordinate
• Enter the bearing (0–360°) and distance (meters or km)
• The projected coordinate is shown and can be copied

26Digit Checksum

Open with Tools → Digit Checksum…

Calculates the digit sum (and iterated digit sum) of one or more numbers. Used in many mystery cache puzzles where you calculate coordinates from the sum of digits in other numbers.

27Midpoint

Open with Tools → Midpoint…

Calculate the geographic midpoint between two coordinates. Enter coordinates A and B; the result is shown in all three coordinate formats and can be copied to the clipboard.

28Distance & Bearing

Open with Tools → Distance & Bearing…

Calculate the great-circle distance and forward/reverse bearing between two coordinates. If a cache is selected, point A is pre-filled.

29Settings

Open with Settings → Settings… (Ctrl+,) or the ⚙ button in the toolbar.

General Tab

Geocaching.com Tab

Advanced Tab

30Choosing Columns

Go to View → Choose columns… to select which columns appear in the cache list and in what order. Drag rows to reorder, check/uncheck to show or hide.

Column visibility and order are saved between sessions.

31Language

Go to Settings → Settings… → General tab → Language. Select your language and click OK. The new language takes effect the next time OpenSAK is started.

Currently supported languages:

Want to help translate? See CONTRIBUTING.md — it only requires translating a single Python file.

32Theme

Go to Settings → Settings… → General tab → Theme:

• Automatic — follows your operating system's light/dark preference
• Light — always light
• Dark — always dark

The theme change takes effect immediately when you click OK — no restart needed.

33Updates

OpenSAK checks for new versions automatically 5 seconds after startup (can be disabled in Settings). When a new version is found, a notification dialog offers three options:

• Open releases page — go to GitHub to download
• Skip this version — suppress notifications for this specific version
• Later — dismiss until next launch

You can also check manually via Help → Check for updates…

34Keyboard Shortcuts

File & Database

Cache List

View & Filters

GPS & Trip Planning

Geocaching Tools

Settings

35Getting Help

This guide was generated from the OpenSAK source code (v1.13.11). Last updated May 2026.