Customize your visualization with tailored-made basemaps


The basemap is the foundational component of a map. It provides context, geographic features, and brand identity for your creations. Every organization is unique, and CARTO allows you to bring your own basemaps to fit your specific needs.

In this tutorial, you'll learn to customize your visualizations in Builder by using tailor-made basemaps. Don't have a custom basemap already? We'll start with the creation of a custom basemap using Maputnik, a free and open-source visual editor.

Prerequisites: You need to be an Admin user to add custom basemaps to your CARTO organization.

In this guide, we'll walk you through:

Creating a Style JSON using Maputnik

  1. Access the online version of Maputnik at Then, click "Open" and select "Zoomstack Night." Zoomstack Night is an open vector basemap provided by Ordnance Survey's OS Open Zoomstack, showcasing coverage of Great Britain.

You might get overwhelmed by all the options available in the UI, but using it is simpler than it seems. To make it easier to recognize the different items you can update in the style, simply click on the map, and Maputnik will display the layers you can customize.

Now that you're more familiar with this tool, let's start customizing the look and feel of this map.

  1. Set the "buildings" layer to blue using this hex color code #4887BD.

  1. For the green spaces, set the "greenspaces" layer to #09927A and "woodland" to #145C42.

  1. To highlight the visualization of both "greenspace names" and "woodland names" labels, increase the size using the below JSON code and set the fill color to white.

  1. Once you're done, export the Style JSON and save it. You'll need this for the next section. Note depending on which style you have used as a template, you may need to include an access token at this point, such as from MapTiler.

Hosting a Style JSON in Github

In this section, we'll showcase how you can host Style JSON files using GitHub to consume them in your CARTO organization. We'll be using a feature called gist, which allows you to host files. Here’s how to do it:

  1. Ensure you have access to GitHub and your own repository and create a new gist. To do so:

    • Go to GitHub and create a new gist.

    • Drag your exported Style JSON into the gist.

    • Make sure the gist is public.

    • Create the public gist.

  1. Now we'll get the raw URL of the hosted Style JSON, to do so:

    • Access the raw version of the gist.

    • Copy the URL of the raw file. This URL will be used to consume the custom basemap in CARTO.

Adding custom basemaps to your organization

Note: You need to be the Admin of your organization to have the rights to add custom basemaps to your CARTO organization.

  1. Go to Organization > Settings > Customizations > Basemaps

  1. Click on "New basemap" to add your custom basemap, completing the following parameters:

    • URL: Enter the gist raw URL of the hosted Style JSON.

    • Name: The name you'd like to provide to your basemap

    • Attribution: Automatically filled but you can edit this if required.

  2. Once the basemap URL has been validated, you can use the interactive map to navigate to the desired basemap extent.

  1. Activate the custom basemap type in the "Enabled basemaps in Builder" section. Doing so, you'll enable all Editors of the organization to access all added custom basemaps.

Creating a map using your custom basemap

  1. Navigate to the Maps section and click on "New map".

  1. Provide the map with a title "Using custom basemaps" and load Bristol traffic accidents source. To do so:

    • Click on "Add sources from..."

    • Navigate to CARTO Data Warehouse > demo data > demo_tables.

    • Select "bristol_traffic_accidents" table.

    • Click "Add source".

The source and related layer is added to the map.

  1. Rename the newly added layer "Traffic Accidents".

  2. Go to the Basemap tab and choose your recently uploaded custom basemap.

  1. Style the "Traffic Accidents" layer:

    • In the Fill Color section, set the color to light yellow.

    • Configure the Size to 4.

  1. Now, you're done with your map creation and ready to share it with others!

Last updated