Tile Map Layers in JavaScript
How to make a tile-based maps in JavaScript with various base layers.
Plotly Studio: Transform any dataset into an interactive data application in minutes with AI. Sign up for early access now.
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 thebelow
attribute). -
layout.map.layers
is an array that defines more layers that are by default rendered above the traces indata
(although this can also be controlled via thebelow
attribute).
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);
}
);
Click to copy
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!
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);
}
);
Click to copy
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);
});
Click to copy
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);
});
Click to copy
> 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/
