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.

The use link in the Mapbox publish screen.

From here, click the Third party link on the left-hand side, choose CARTO from the top and copy the Integration URL.

Get the CARTO url in Mapbox.

Now go log into your Gaia GPS account (in a web browser, not the app). Click your avatar in the upper right-hand corner and choose Map Sources.

How to access map sources in Gaia GPS.

This will take you to a screen where you can add and manage your custom map sources. I already have a few listed, since I’ve done this process before, but your list will probably be empty.

What we want to do is add the URL we copied a moment ago from Mapbox as a custom map source in our Gaia account. To do this, click the Import an External Map Source button.

Import a custom map source into Gaia GPS.

This will take us to yet another screen where we can add our custom map source. To start with, you will want to give your map source a name. I’m just going to call mine Custom Map Example.

Name the custom map in Gaia GPS.

Give your custom map source a meaningful name.

Now paste the URL you copied from Mapbox into the link text field of this page.

Paste the URL to the custom map source in Gaia.

Right below this is an area to enter the minimum and maximum zoom levels of your custom map.

Enter the min and max zoom levels for the map source in Gaia.

NOTE: If you’re not sure what the minimum and maximum zoom levels of your custom map source, you can get these values from Mapbox. Simply go to your Mapbox Studio account, click the Tilesets tab and click on your custom tileset. You will be able to see these values there.

How to view zoom extents of custom map source in Mapbox.

You can get the minimum and maximum zoom values from within the tileset information in Mapbox.

The next section allows you to reverse the X and Y coordinates of the map. This is uncommon and you should be able to ignore this section.

The final section allows you to preview your custom map source. By default, it is previewing the area around Berkeley, California. You will want to enter a set of coordinates that are covered by your custom map to preview it. Since my dataset is for the Red River Gorge, I simply entered the coordinates of Gray’s Arch.

Preview of a custom map source in Gaia GPS.

If everything has gone well, you should see a preview of your custom map. If so, you can click the Add this map source button.

Add custom map source to Gaia GPS.

Step 4: Use the Map Source in the Gaia App

Woo, this sure is a long, convoluted process, isn’t it?! The good news is that the hard part is over with and we should finally be able to use our custom map within the Gaia App!

We should now be able to add our custom map source to the Gaia map just like adding any other map layer. To do so, open Gaia on your phone and choose the layers menu.

Access the layers menu in Gaia GPS (IOS).

From there click the Edit button.

Edit map sources in Gaia GPS.

This will open a menu of all the map source options. There should be a category called Custom Imports at the bottom. Click this option.

Access custom map sources in the Gaia GPS app.

Within this menu, you should see your custom map source listed. Tap on it.

Select a custom map source in Gaia GPS.

You can now hit the back button until you get back to the initial map sources dialog. If you scroll down you should now see your custom map as an option to add to the map in Gaia. Simply tap it to add it to the main map.

Add custom map layer to a Gaia GPS map.

This will add the custom map source to the visible layers section. You will likely need to slide the opacity slider all the way to the right to make it fully visible.

Adjust layer opacity in Gaia GPS.

Click Done and you should now have your custom map displayed in Gaia!

Custom LIDAR map loaded into Gaia GPS.

Woo hoo, our custom map is now available in the Gaia app!

While this certainly isn’t a convenient or streamlined process, it does work. At this point we can use this layer just like we would any other in Gaia, including being able to download it for offline use.

Hopefully in future versions of Gaia they will come up with a much better way of doing this! In the meantime, this method will get the job done.