Adding a Custom Map To The IOS Version of Gaia GPS

I am a huge fan of Gaia GPS. I use it for everything from GPS navigation, to logging my hikes, cataloging the various points of interest I come across on my adventures, and plenty of other things in between. It’s a truly wonderful piece of software, where most things are extremely well thought out and easy to use.

That is, except for adding a custom map source in the IOS version of Gaia.


I have a friend, Chris (who you probably know from the Kentucky Waterfalls Database), who enjoys making maps in his free time. These maps that he creates are beautiful and amazingly detailed.

To make a long story short, I’ve spent the past month or two working on a piece of software to make finishing these maps of his a little bit easier. In exchange, he’s given me some of the LiDAR maps he’s generated for some of Kentucky.

These maps are incredibly detailed and insanely useful for planning routes, finding waterfalls and all sorts of other tasks. As such, it’s a no brainer that I’d want to be able to use the LiDAR maps in Gaia GPS.

In doing a little bit of research, I found that, in the Android version of Gaia, you can simple import a MbTiles database of the custom map tiles and use it. Unfortunately, things are not nearly as simple in IOS.

Getting it to Work on IOS

For whatever reason, the IOS version of Gaia will not allow you to simply import a MbTiles file into the app. I suspect this is a result of how locked down the IOS filesystem is, but I digress. Luckily, there is a workaround, though, it is a pain.

Step 1: Creating a Custom Tileset in Mapbox

To make this work, you will need to create a Mapbox account. Mapbox is an online tool for creating custom maps. It is a paid service, but there is a free tier that has provided me everything I’ve needed to make this work.

Once you’ve got your account created, you want to open up Mapbox Studio.

Demonstration of how to get to Mapbox Studio.
When logged in, click your avatar and select Studio from the dropdown menu.

Once we’re in Mapbox studio, we want to start by creating a new Tileset. To do this, click the Tilesets link in the upper right-hand corner.

How to get to the tilesets in Mapbox.

From here, click the New tileset button and upload your MbTiles file.

How to create a new tileset in Mapbox.

Depending on the size of your MbTiles database, this upload can take quite a while to finish. To give you an idea, it took well over an hour for my 7Gb file for Red River Gorge to upload and process. Once it completes, however, you will see your custom tileset listed.

List of custom tileset on Mapbox.

Step 2: Create a Custom Map in Mapbox

Once our custom tileset is uploaded to Mapbox we need to create a custom map that utilizes these tiles. Mapbox refers to this as creating a style.

To start, click the Styles link in the upper right-hand corner.

How to access map styles in Mapbox.

We want to start by creating a new, blank style. To do this, click the box that says More options.

More styles in Mapbox.

This will pop up a new dialog. From here, click the button that says Start blank.

How to create a new blank map in Mapbox.

This will open the Mapbox style editor. The map will be empty, for the moment, since we started with a new, blank map.

To start with, we will want to give our custom map a name, so we know what it’s a map of. This can be done by replacing the text in the upper left-hand corner.

How to name a map in Mapbox.

Now we are going to add our custom tileset to the map. To do this, click the new layer button and select your custom tileset in the flyout. In this example, I will use my Red River Gorge LiDAR tileset.

How to add a custom layer to a map in Mapbox.

Once you add the data to the map, you will likely get a message informing you that the map isn’t currently centered on the area your tileset covers. If you want to preview the tileset, click the button that says Go to data.

Go to data in Mapbox.

It’s a good idea to preview the data to ensure everything looks right.

Clicking this button should center your map on your custom tile data, allowing you to preview what it’ll look like.

Previewing the LiDAR map in Mapbox.

Just look at how pretty that map is!

Assuming everything looks good with your custom tileset, you’re good to go to the next step. If something is wrong, the problem is likely with the MbTiles database you uploaded in step one. Diagnosing these problems is way outside the scope of this tutorial!

Step 3: Add The Custom Map to Your Gaia Account

Now that we’ve created a custom map in Mapbox, we want to add this as a custom map source in our Gaia account. This process is done in a web browser, not in the Gaia app (yes, I realize this is a round-about process).

To start, click the Publish button on your map in Mapbox. This will open up another dialog where you will again hit the Publish button.

Publish your map in Mapbox.

This will bring up another dialog that tells you your map was successfully published. In this dialog, you want to click the Use link.