Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

CARTO basemap styles

CARTO Basemap styles for web and mobile, raster and vector. Preview and compare with different viewers here.

This repository has working copies of basemap cartographic styles for different targets

Source data

The styles are based on current version of OpenMapTiles data schema and vector tiles:

The cartography

All the styles are "soft" in a sense that they are meant to be used as background or basemap below data layers. These are not really meant to be used as stand-alone map by itself, something you'l get from Google, Here and other general maps.

  1. Voyager - colored map, the default basemap in CARTO Builder
  2. Positron - light gray map, good for point data
  3. Dark Matter - dark gray map, good for polygon/line data

voyager positron dark-matter

1. Web raster basemaps

Service public info: The structure of the URLs to call the service is the following: https://{s}{style}/{z}/{x}/{y}{scale}.png , where:

  • {s}: one of the available subdomains, either [a,b,c,d]
  • {z} : Zoom level. We support from 0 to 20 zoom levels in OSM tiling system.
  • {x},{y}: Tile coordinates in OSM tiling system
  • {scale}: OPTIONAL "@2x" for double resolution tiles
  • {style}: Map style, possible value is one of:

Limitations: free usage for up to 75,000 mapviews per month, none-commercial services only. For bigger usage and other cases contact CARTO sales for enterprise service key.

Sample with Leaflet JS:

layer = L.tileLayer('https://{s}{z}/{x}/{y}' + (L.Browser.retina ? '@2x.png' : '.png'), {
   attribution:'&copy; <a href="">OpenStreetMap</a>, &copy; <a href="">CARTO</a>',
   subdomains: 'abcd',
   maxZoom: 20,
   minZoom: 0


  • Style is written in CartoCSS using Mapbox Studio Classic (, and shared here as Mapbox Studio Classic project
  • Raster tiles generated by Mapnik tilelive-vector using Mapnik-XML styling.
  • File folder in this repo: /cartocss/web

File structure

Styles use as much shared styling as possible. Shared cartocss (.mss) files are in /shared folder, and linked with symlinks to different style projects, as MB Studio requires files in single folder. Same symlink-based sharing is used for Fonts and Images subfolders. Every style has following unique files:

  • project.yml - main project file. It is important to have here list of layers, as this determines order of layer rendering
  • style.mss - specific values for style variables
  • project.xml - generated file by MB Studio Classic. Normally is not edited manually, but real server uses this for real styling

2. CARTO Mobile SDK live basemaps

  • folder cartocss/mobile-sdk-styles
  • these are taken from "Web Basemaps" .mss files (CartoCSS) and are modified to have vector rendering specifics - e.g. language and 3D display, smooth zoom variables
  • Style modification from web basemap to mobile basemap is manual process
  • You can try our experimental app to edit mobile basemap styles with a mobile device: Android tablet or iPad. This gives you direct user experience of your style right on mobile.
  • Technical details how our Mobile CartoCSS is different from web CartoCSS: . There are some mobile-specific extensions and also some limits.
  • How to use the styles as custom styles in your mobile app:
  • Every style has mobile-specific .json metafile (e.g. voyager.json). This is SDK-specific format, somewhat similar to project.yml file in MB Studio Classic. Defines also order of layers, and some SDK-specific additional parameters. It has also file sizes and checksums, this is used in online style server to identify style updates.
  • Note that MBStudio generated .xml is not used in mobile

3. Vector styles for web

Mapbox-gl style

  • folder: /mapboxgl
  • Master style is file /tools/style_tpl.json . It uses template placeholders for variable values for different styles
  • Different styles are /style-name/style-name_vars.json files
  • You should use tools/ script to generate specific style from template and _vars.json file. The ready-made style-name.json files are generated and for reference only.
  • Master style and variables files are manually created from a working style


Tangram styles

  • folder: /tangram
  • Can be edited using Tangram Play
  • Use it 'as is', not supported or developed anymore by CARTO