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.

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.

   

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

   

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.

   

Copyright Attributions

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.

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

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

MAPBOX

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.

WMS/WMTS

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.

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.

TILEJSON

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.

NASA

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.