🗺️ otm-dl - OpenTopoMap Downloader

A fast, user-friendly CLI tool to download Garmin OpenTopoMap files in bulk based on YAML configuration.

---

✨ Features

• 📦 Bulk downloads of multiple countries in one command
• 🎯 Per-country selection of Garmin, contour, and Basecamp maps
• 🔄 Update checking using the latest timestamp from garmin.opentopomap.org
• 🎨 Structured, colored logging with optional debug output
• 🛡️ Resilient behavior: invalid countries or failed downloads do not stop others
• 🐛 Debug mode for verbose troubleshooting

---

📦 Installation

From Source

git clone https://github.com/joanbono/otm-dl.git
cd otm-dl
go mod tidy
go build -o otm-dl

---

🚀 Quick Start

1. Create configuration

Default location: ~/.otp-dl/config.yaml

Example:

- country:
    andorra:
      garmin: true
      contour: true
      basecamp: false
    spain:
      garmin: false
      contour: false
      basecamp: true

This will:

• Download Garmin and Contours maps for Andorra
• Download only Basecamp maps for Spain

2. Run downloads

# Use default config and current directory
$ otm-dl download

# Specify config file and output directory
$ otm-dl download -c ~/.otp-dl/config.yaml -o ~/Downloads/Maps

# Enable debug logging
$ otm-dl download -d

3. Check for new map versions

otm-dl update
otm-dl update -d   # with debug logging

The update command compares the date stored in $HOME/.otp-dl/last-download.txt with the current date parsed from the OpenTopoMap HTML and informs you if a newer version is available.

---

📖 Command Reference

Top-level

$ otm-dl [command] [flags]

Commands

Command	Alias	Description
download	dl	Download map files according to the YAML config
update	—	Check if a newer map version is available

Global Flags

Flag	Short	Default	Description
--debug	-d	false	Enable verbose debug logging

download Flags

Flag	Short	Default	Description
--config	-c	~/.otp-dl/config.yaml	Path to configuration YAML file
--out	-o	current working directory	Directory where files are downloaded

Examples

# Basic usage with defaults
otm-dl download

# Use custom config and output directory with debug
otm-dl download -c /path/to/config.yaml -o /path/to/output -d

---

⚙️ Configuration Format

The configuration file is a YAML list where each item contains a country block. Inside country, keys are country names (case-insensitive), and values are the map types to download.

- country:
    <country-name>:
      garmin:   <true|false>
      contour:  <true|false>
      basecamp: <true|false>

Example:

- country:
    andorra:
      garmin: true
      contour: true
      basecamp: false
    spain:
      garmin: true
      contour: false
      basecamp: true
    bosnia_herzegovina:
      garmin: true
      contour: true
      basecamp: true

Country name handling

Country names in YAML are normalized as follows:

• Case-insensitive: Andorra, andorra, ANDORRA are equivalent
• Spaces are converted to underscores for URL slugs:
  czech republic → czech_republic
• Some special mappings are handled explicitly, for example:
  • bosnia and herzegovina → bosnia_herzegovina
  • czech republic → czech_republic
  • united kingdom → great_britain

If a country name cannot be mapped to a known slug or a download URL returns 404, the tool logs a warning but continues with other countries.

---

🧠 Behavior Details

Downloads

For each country and map type enabled in the config, the tool constructs URLs like:

• Garmin:
  https://garmin.opentopomap.org/europe/<slug>/otm-<slug>.zip
• Contours:
  https://garmin.opentopomap.org/europe/<slug>/otm-<slug>-contours.zip
• Basecamp:
  https://garmin.opentopomap.org/europe/<slug>/otm-<slug>-basecamp.zip

Professional, user-friendly messages are printed, e.g.:

• Downloaded OpenTopoMap for Andorra
• Downloaded Contours for Andorra
• Downloaded Basecamp for Andorra

Error handling

• Invalid country names: A warning is logged and processing continues
• HTTP errors / missing files: A warning is logged for that file; other downloads continue
• At the end, a summary indicates whether there were warnings

Version tracking

Each successful download run:

• Scrapes the OpenTopoMap HTML for the Andorra row
• Extracts the last update timestamp (e.g. 2026-01-23 03:18:44)
• Stores the date part (2026-01-23) into $HOME/.otp-dl/last-download.txt

The update command:

• Reads last-download.txt
• Fetches the current update date from the server
• Informs you whether a newer version is available

---

🛠️ Development

Requirements

• Go 1.21 or newer

Dependency Setup

From the project root:

go mod tidy

(If needed, explicitly:)

go get github.com/spf13/cobra@latest
go get github.com/sirupsen/logrus@latest
go get github.com/PuerkitoBio/goquery@latest
go get gopkg.in/yaml.v3@latest
go get github.com/briandowns/spinner@latest
go get github.com/fatih/color@latest

Build

go build -o otm-dl

Project Layout

.
├── main.go
├── internal/
│   ├── downloader.go   # download command & logic
│   └── update.go       # update command & logic
├── go.mod
├── go.sum
└── README.md

---

🐛 Troubleshooting

“cannot read config file”

• Ensure ~/.otp-dl/config.yaml exists, or use -c to point to a config:

  otm-dl download -c /path/to/config.yaml

“Skipping invalid country”

• Check the spelling of the country in your config
• For complex names, verify how the country is named in OpenTopoMap or adjust to one of the supported patterns

“HTTP 404” / “file not found”

• The specific map type may not exist for that country
• The tool logs a warning and continues with the rest

Run with debug for more context:

otm-dl download -d

---

📝 License

This project is licensed under the MIT License.
See the LICENSE file for details.

---

🤝 Contributing

Contributions are welcome:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m "Add my feature"
4. Push the branch: git push origin feature/my-feature
5. Open a Pull Request

---

⭐ Acknowledgements

• OpenTopoMap for the map data and Garmin exports
• Go ecosystem: Cobra, Logrus, GoQuery and others that make this CLI ergonomic

If this project is useful to you, please consider starring the repository on GitHub.
It helps others discover it and motivates further improvements!