Inserting External Basemaps

Styling Guides

Inserting External Basemaps

In addition to the default basemaps offered in CARTO, you may add external third-party basemaps to customize your map background. CARTO Builder allows you specify an external resource and insert a defined url to add the style.

With the exception of NASA imagery, external basemaps are rendered based on tile services. By selecting a basemap source, you are requesting existing, pre-generated, image tiles from a remote server. CARTO uses a proxy to translate URLs from the Internet. Any external basemap source that you want to apply must be available via a public URL, in order to be rendered correctly.

Once an external basemap is inserted into CARTO, the performance rendering of the map tiles are dependent on the external service that you selected.

Inserting an External Basemap

For this guide, let's insert a public XYZ basemap as the source for our map background.

  1. From the LAYERS pane in Builder, click on the basemap name.

    The basemap options appear.

  2. For the Source, select CUSTOM.

  3. Click + from the Style options to add an external resource.

    Any previously added custom basemaps will appear in this section.

    Select custom basemap source

    The Add a custom basemap options appear. Select the tabs across the top to select from XYZ, MAPBOX, WMS/WMTS, TILEJSON, or NASA.

    Custom basemap options

  4. For this example, keep XYZ as the external resource.

  5. Insert http://{s}{z}/{x}/{y}.png as the basemap.

    This is an example standard tile layer, provided by OpenStreetMap.

    If CARTO cannot validate the public url, a warning message appears. Ensure that you follow the required parameters for each tile service.
  6. Click ADD BASEMAP to add the external basemap as a resource.

The external basemap appears as the map background.

Custom basemap applied

Legally, many basemap providers request proper attributions if you are using their imagery in maps. If you are using external basemaps, it is a suggested best practice to include the basemap source in the map attributions.

  • From the map name menu options in Builder, click Edit metadata to add the description for the external resource for the basemap.

Edit map metadata

Required Parameters for External Basemaps

There are certain parameters (for public, external basemaps) that are required in order to correctly render map tiles. Typically, they are urls that define the size and zoom level of the tile service. When you are adding custom basemaps in Builder, CARTO provides an example url schema during the insert process.

The following external resources can be added as the basemap source in CARTO. Ensure that you follow the required parameters, according to the selected tile service.


XYZ Templates enable you to access many other basemaps, including those from OpenStreetMap and Stamen. Insert the basemap URL and click ADD BASEMAP.

XYZ url Options Examples
Template https://{s}.{domain}.com/{basemap}/z/x/y.png

Is usually an image file that contains zyx coordinates. The following XYZ basemaps apply these parameters. Note that the schema varies, depending on the basemap:

- Stamen Toner: http://{s}{z}/{x}/{y}.jpg

- Stamen Terrain:{z}/{x}/{y}.jpg

- Stamen Watercolor:{z}/{x}/{y}.jpg

- OpenStreetMap Topography: http://{s}{z}/{x}/{y}.png
TMS Click the TMS checkbox if the XYZ basemap contains inverted Y coordinates for the tile map service.
External Resources XYZ Standards, OpenStreetMap Slippy Tilenames


Mapbox is a service which lets you customize the design of a basemap with custom colors and elements. If you have a Mapbox account, insert your Mapbox id/url and Mapbox access token to add the basemap.

Map styles created with Mapbox classic urls can be used for basemaps in CARTO, since they render image tile sets. If you enter a new Mapbox Studio url, which renders images in WebGL (Web Graphics Library), an error appears.

Be mindful that map views to your MapBox baselayers will be counted in your MapBox account and may lead to additional charges.


A WMS, or Web Map Service, enables you to connect to online generated map images by a map server using data from a GIS database.

  • Insert your WMS/WMTS URL and click GET LAYERS to fetch the layers from the web service provider.
  • Select the layer to be added and click ADD THIS.

The following example displays how a WMTS web service url can be added as a basemap.

Example WMTS basemap

WMS/WMTS url Options Example

Is usually a url that contains server tiles accessed from web server visualizations. CARTO only supports WMS files containing data that uses EPSG:900913 (Web Mercator) or EPSG:3857 coordinates.

The following WMS/WMTS example urls apply parameters based on the web service provider:

- Orthoimagery of Spain, provided by National Geographic Information Center of Spain:

- USGS Topography Map, provided by The National Map:
Resources WMTS Standards, WMS Service List at NGDC, USGS Web Map Services, WMS Tile Layer Example from Microsoft

To avoid errors, ensure that the service supports the projections used by CARTO. If you are able to get the layers, but not add them, you already have those layers added to your account.


Enables you to insert an open platform, web map by inserting the TileJSON url. A TileJSON basemap contains tiles, minzoom, and maxzoom as mandatory fields. A typical url schema may contain: http://{domain}.com/tiles.json?{foo=bar}.

For example, is a TileJSON layer from OpenLayers.


Enables you to select a basemap provided by NASA Worldview. Select a date from which you want a global basemap and indicate Day (a day map changes based on the day selected) or Night.