CSV to GPX Converter for geocaching.com

You have a file with final coordinates for some mysteries. Editing every geocache coordinate manually takes way too long. Therefore, I wrote a small application which converts a csv to a gpx file, and a user guide on how to automatically upload the gpx file to geocaching.com. The provided GSAK macros automatically add or update the coordinates for each geocache.

Before we begin, you might have to trim your input file a bit to match the requirements for the converter. Maybe later, I will make the converter more flexible.

From CSV to GPX

Each row of the CSV file has to contain the GC number and the coordinates for the geocache in the same position. That is the minimal requirement for a successful upload via the geocaching.com API using GSAK.

For example, a valid CSV file looks like this

The first entry of each row contains the GC Code. The second and third represent the coordinate. In this example, the delimiter is a colon.

The application parses one row after the other and converts it into a GPX format. If a row could not be parsed, it is skipped. The resulting gpx file after a successful conversion of the before shown example looks like this

At the moment, the script can only convert coordinates in decimal degrees.

1. Setup GSAK and macros

First, you need to download GSAK (Geocaching Swiss Army Knife). It is the all-in-one tool for Geocachers. Some of the features are Geocaching.com live api, online logging, conversion to many mapping formats, and extensibility with macros.

To automatically upload and correct the final coordinates, we will make use of two macros.

Download SetCorrectedFlag.gsk and CorrectedCoord2GCcom.gsk from the GSAK forum.

The first macro will add the corrected coordinates flag to all caches in the current database or filter. The second macro transfers the corrected coordinates set in GSAK on the currently selected cache to the Geocaching.com online cache page. The result will be the same as if you manually edited the coordinates on the online cache page. But it will save you hours of your time!

Open GSAK and go to Macro -> Execute -> Install or press CTRL+M -> Install. Select one of the two .gsk files and click install. Repeat for the second macro.

2. The CSV to GPX Converter

The converter (and the code) itself is available on my Github page under https://github.com/matthiassommer/csv2gpx. Download the executable csv2gpx.exe or clone the repository and build it with go build.

Run the application with

The first argument defines the path to the raw input file, the second defines the target location and name of the resulting gpx file.

3. Upload coordinates with GSAK

  1. Now, import the converted GPX file in GSAK (CTRL+O)
  2. Run the macro SetCorrectedFlag (CTRL+M and doubleclick on it). This will set a flag on all your imported geocaches so the second macro can pick them up for upload.
  3. Then, run the macro CorrectedCoord2GCcom and wait until all coordinates are uploaded. A popup shows the progress.
  4. Go to the geocache’s listing to verify that the coordinate was successfully added or updated.

Docker build

To get more familiar with Docker, I wrote Dockerfiles for both implementations. In terms of Go, I used a multistage setup which builds the go application and runs it. The Dockerfile for the python variant is shorter as it only copies the necessary files and executes the python script.

The according readme.md files also contain the instructions to build and run the Dockerfiles.

Further reading

The application is available on Github, written in Golang as an executable, and also implemented as a Python script. There, you can also find the GSAK macro files and a readme. If you find bugs or would like to have a certain feature, just write it in the comments below.

By the way, if you are interested, here is the Swagger specification for geocaching.com Rest API.