This article is for EarthRanger Admin users who want to add custom basemaps to improve map readability or integrate organization-specific map styles. EarthRanger includes default basemaps that work for many deployments, but custom basemaps allow you to tailor the map experience to your operational needs. This guide explains how to add a custom basemap in EarthRanger Admin, with additional guidance for Mapbox-based basemaps.

Before you begin

Before adding a custom basemap, keep the following in mind:

• You must have Admin access in EarthRanger to manage basemaps.
  (Confirm if a specific Admin role or permission is required.)
• EarthRanger supports basemaps provided via WMS or tile services (for example, ESRI, ArcGIS, or Mapbox).
• Most EarthRanger custom basemaps are built using Mapbox. In these cases, the Map Layer Service Type is typically set to Tile Server.

Add a new basemap in EarthRanger Admin

1. Navigate to: EarthRanger Admin > Basemaps.
   You will see a list of existing default and custom basemaps.
2. Select Add Basemap.
3. Enter a Name for the basemap.
   Use a name that is unique and easy for your team to identify.
4. Configure the Tile Layer Attributes:
   1. Map Layer Service Type: Select the appropriate service type. For Mapbox basemaps, select Tile Server.
   2. Title: Enter the display name that will appear in the EarthRanger web map basemap selector.
   3. URL: Paste the basemap service URL. For Mapbox, this is the Integration URL generated in Mapbox Studio.
   4. Icon URL (optional): Enter a URL for an icon to display in the EarthRanger web interface.
5. Choose one of the following options:
   1. Save – saves the basemap and returns to the basemap list.
   2. Save and continue editing – saves and keeps the basemap open.
   3. Save and add another – saves the basemap and immediately creates a new one.
       

Expected result:
The basemap is saved and becomes available in the EarthRanger web map basemap selector.

Create a Mapbox basemap for EarthRanger

If you are using Mapbox (the most common approach), complete the steps below before adding the basemap to EarthRanger.

Prepare your data

Ensure your geospatial data is in a Mapbox-compatible format, such as:

• GeoJSON
• GeoTIFF
• Supported vector tile formats

Upload a tileset to Mapbox

1. Log in to your Mapbox account.
2. Navigate to Tools > Data Manager.
3. Select New tileset.
4. Choose Upload a file, then upload your dataset.
   
   After the upload completes:
5. Open the tileset.
6. Select Share & Use.
7. Set the visibility to Public.
   (Confirm whether private/authenticated tilesets are supported.)
8. Copy the Tileset ID.

Style the basemap in Mapbox Studio

1. From the Mapbox home page, navigate to Tools > Style Editor.
2. Add your tileset to a style.
3. Customize the map appearance, such as:
   1. Zoom levels
   2. Colors and saturation
   3. Background layers
   4. Any required transformations
4. Select Publish when styling is complete.

Get the Integration URL

1. In the Style Editor, select Share.
2. Under Developer resources, choose Third Party.
3. From the list, select CARTO.
4. Copy the Integration URL.

Use this Integration URL in the URL field when adding the basemap in EarthRanger Admin.

Best practices for basemaps

When adding or designing basemaps, consider the following best practices:

Ensure compatibility with overlays
Your basemap should work well with EarthRanger data layers such as features, patrol tracks, and boundaries.

Choose appropriate visual contrast

• Satellite imagery can obscure small features.
• Street or vector maps may lack detail in remote areas.Select a basemap that complements your operational data.

Balance quality and performance

High-resolution basemaps provide better detail but can impact performance. Large or complex tilesets may slow loading times when combined with heavy datasets.

Use clear naming conventions

Basemap names should make it easy for users to understand when and why to use them.