Tile Map Layers in JavaScript

How to make a tile-based maps in JavaScript with various base layers.

New to Plotly?

Plotly is a free and open-source graphing library for JavaScript. We recommend you read our Getting Started guide for the latest installation or upgrade instructions, then move on to our Plotly Fundamentals tutorials or dive straight in to some Basic Charts tutorials.

How Layers work in Tile-based Maps

If your figure contains one or more traces of type Scattermap, Choroplethmap or Densitymap, the layout object in your figure contains configuration information for the map itself. The map is composed of various layers, of three different types.

layout.map.style defines the lowest layers, also known as your "base map"
The various traces in data are by default rendered above the base map (although this can be controlled via the below attribute).
layout.map.layers is an array that defines more layers that are by default rendered above the traces in data (although this can also be controlled via the below attribute).

OpenStreetMap tiles

Here is a simple map rendered with "open-street-map" tiles.

d3.csv(
	"https://raw.githubusercontent.com/plotly/datasets/master/2015_06_30_precipitation.csv",
	function(err, rows) {
		function unpack(rows, key) {
			return rows.map(function(row) {
				return row[key];
			});
		}

		var data = [
			{
				type: "scattermap",
				text: unpack(rows, "Globvalue"),
				lon: unpack(rows, "Lon"),
				lat: unpack(rows, "Lat"),
				marker: { color: "fuchsia", size: 4 }
			}
		];

		var layout = {
			dragmode: "zoom",
			map: { style: "open-street-map", center: { lat: 38, lon: -90 }, zoom: 3 },
			margin: { r: 0, t: 0, b: 0, l: 0 }
		};

		Plotly.newPlot("myDiv", data, layout);
	}
);

Using "layout.map.layers" to Specify a Base Map

If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set layout.map.style to "white-bg" and to use layout.map.layers with below to specify a custom base map. If you omit the below attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!

Base Tiles from the USGS

Here is an example of a map which uses a public USGS imagery map, specified in layout.map.layers, and which is rendered below the data layer.

d3.csv(
	"https://raw.githubusercontent.com/plotly/datasets/master/2015_06_30_precipitation.csv",
	function(err, rows) {
		function unpack(rows, key) {
			return rows.map(function(row) {
				return row[key];
			});
		}

var data = [
	{
		type: "scattermap",
		text: unpack(rows, "Globvalue"),
		lon: unpack(rows, "Lon"),
		lat: unpack(rows, "Lat"),
		marker: { color: "fuchsia", size: 4 }
	}
];

var layout = {
	dragmode: "zoom",
	map: {
		style: "white-bg",
		layers: [
			{
				sourcetype: "raster",
				source: ["https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"],
				below: "traces"
			}
		],
		center: { lat: 38, lon: -90 },
		zoom: 3
	},
	margin: { r: 0, t: 0, b: 0, l: 0 }
};

Plotly.newPlot("myDiv", data, layout);
	}
);

Base Tiles from the USGS, radar overlay from Environment Canada

Here is the same example, with in addition, a WMS layer from Environment Canada which displays near-real-time radar imagery in partly-transparent raster tiles, rendered above the go.Scattermap trace, as is the default.

d3.csv('https://raw.githubusercontent.com/plotly/datasets/master/2015_06_30_precipitation.csv', function(err, rows){
      function unpack(rows, key) {
          return rows.map(function(row) { return row[key]; });
		}

var data = [{
        type: 'scattermap', text: unpack(rows, 'Globvalue'),
        lon: unpack(rows, 'Lon'), lat: unpack(rows, 'Lat'),
        marker: {color: 'fuchsia', size: 4}
    }];

var layout = {
	dragmode: 'zoom',
	map: {
		style: 'white-bg',
		layers: [
			{
            "below": 'traces',
            "sourcetype": "raster",
            "source": [
                "https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"
            ]
        },
			{
             sourcetype: "raster",
			 source: ["https://geo.weather.gc.ca/geomet/?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&BBOX={bbox-epsg-3857}&CRS=EPSG:3857&WIDTH=1000&HEIGHT=1000&LAYERS=RADAR_1KM_RDBR&TILED=true&FORMAT=image/png"]}],
		below: 'traces',
		center: {lat: 38, lon: -90}, zoom: 4},
	margin: {r: 0, t: 0, b: 0, l: 0},
	showlegend: false};

Plotly.newPlot('myDiv', data, layout);
  });

Dark tiles

var url = "https://maplibre.org/maplibre-gl-js/docs/assets/significant-earthquakes-2015.geojson";

d3.json(url, (err, raw) => {
  var lon = raw.features.map(f => f.geometry.coordinates[0]);
  var lat = raw.features.map(f => f.geometry.coordinates[1]);
  var z = raw.features.map(f => f.properties.mag);

  var data = [
    { type: "scattermap", lon: lon, lat: lat, z: z, hoverinfo: "y" }
  ];

  var layout = {
    map: { style: "dark", zoom: 2, center: { lon: -150, lat: 60 } },
    margin: { t: 0, b: 0 }
  };

  Plotly.newPlot('myDiv', data, layout);
});

Mapbox Maps and Access Tokens

> Mapbox traces are deprecated and may be removed in a future version of Plotly.js.

The word "mapbox" in the trace names and layout.mapbox refers to the Mapbox GL JS open-source library. If your basemap in layout.mapbox.style uses data from the Mapbox service, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. If your basemap uses data from the Stadia Maps service (see below for details), you'll need to register for a Stadia Maps account and token.

To use a token, provide it as mapboxAccessToken in the setPlotConfig function, or as a variable that would be passed as an argument of newPlot. If your layout.mapbox.style does not use data from the Mapbox service, you do not need to register for a Mapbox account.

Base Maps in `layout.mapbox.style`

The accepted values for layout.mapbox.style are one of the following tiles.

"white-bg" yields an empty white canvas which results in no external HTTP requests
"open-street-map", "carto-positron", or "carto-darkmatter" yield maps composed of raster tiles from various public tile servers which do not require signups or access tokens
"stamen-terrain", "stamen-toner" or "stamen-watercolor" yield maps composed of raster tiles from the Stadia Maps service and require a Stadia Maps account and token.
"basic", "streets", "outdoors", "light", "dark", "satellite", or "satellite-streets" yield maps composed of vector tiles from the Mapbox service, and do require a Mapbox Access Token or an on-premise Mapbox installation.
A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/