Hey! This content applies only to previous CARTO products

Please check if it's relevant to your use case. On October 2021 we released a new version of our platform.
You can learn more and read the latest documentation at docs.carto.com

Tutorials  /  Using Builder  /  Basemaps

Inserting External Basemaps

Describes how to add and insert external third-party basemaps in CARTO Builder.

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 list 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}.tile.openstreetmap.org/{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.

CHEATSHEET: Attribution Requirements

Attributions represent the data sources used in your map, which may have copyright protections. There are several methods of defining map attributions. For more information, see how CARTO defines attributions as part of our Terms of Service.

  • Automatic Attributions - When you choose a basemap, export a map as an image, or download a map as a .carto file with CARTO Builder, map attributions are automatically included.
  • Dataset Attributions - When you are using third-party data for your maps, you may need to provide attributions about the data sources. To add attributions to a dataset, use the "Edit metadata" option, which is accessible from the dataset name menu option.
  • Print Attributions - When you are printing CARTO maps, be sure map attributions are included. For details, see Printing Map Images.
  • 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}.stamen.com/toner/{z}/{x}/{y}.jpg

- Stamen Terrain: http://tile.stamen.com/terrain/{z}/{x}/{y}.jpg

- Stamen Watercolor: http://tile.stamen.com/watercolor/{z}/{x}/{y}.jpg

- OpenStreetMap Topography: http://{s}.tile.opentopomap.org/{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

CHEATSHEET: Ordnance Survey Basemap

The OS Maps API is a tiled web map service from the Ordnance Survey that provides four different cartographic styles of mapping in a EPSG:3857 (Web Mercator) projection. The basemap provides a consistently detailed map of Great Britain. (See the OS Maps API documentation for details about basemap styling and projections). These basemaps can be added in CARTO by inserting the XYZ basemap option.

All OS Maps API URLs have a base path and an Api Key; which is provided as a query parameter on the end of the URL. For example https://api2.ordnancesurvey.co.uk/mapping_api/v1/service/zxy/EPSG:3857/Outdoor 3857/{z}/{x}/{y}.png? key={my_api_key}.

You must have an Api Key that connects the API request to a user account. Register for an account and OS Maps API key.

CHEATSHEET: DigitalGlobe Imagery and Basemaps

If you are using the DigitalGlobe Maps API with CARTO, you can add their imagery and basemaps by inserting an XYZ external basemap.

All DigitalGlobe Maps API URLs have a base path and an Api Key provided by Mapbox; which is included as a query parameter on the end of the URL. For example https://api.tiles.mapbox.com/v4/digitalglobe.nal0g75k/{z}/{x}/{y}.png?access_token= {your Mapbox access token}.

Enterprise account plans are eligible to receive the most recent satellite imagery. Please contact us to activate this service for your account or request a demo for more information.


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
Template http://openlayers.org/en/v3.5.0/examples/data/ogcsample.xml

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: http://www.ign.es/wmts/pnoa-ma?request=GetCapabilities&service=WMTS

- USGS Topography Map, provided by The National Map: https://basemap.nationalmap.gov/arcgis/services/USGSTopo/MapServer/WMSServer
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, https://api.tiles.mapbox.com/v3/mapbox.geography-class.json?secure 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.