Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 42 ยท Maps and 3D

Tile Maps and Density Maps

Use Plotly street maps built from map tiles: scatter_map, choropleth_map, density heatmaps, map styles, zoom and center, plus the older mapbox names and tokens.

The outline maps from the previous lesson are perfect for countries. When you need streets, buildings and zoom from a continent down to one neighborhood, you want a tile map. A tile map is made of small square images (tiles) that the browser downloads for the area and zoom level on screen, and your data is drawn on top. Delivery tracking, store locators, taxi pickups and earthquake epicenters all use it.

Current Plotly (version 5.24 and later in Python, with Plotly.js 3) calls these traces scattermap, choroplethmap and densitymap, built on the open-source MapLibre library. Older code uses scattermapbox, choroplethmapbox and densitymapbox and px.scatter_mapbox; those still work but are deprecated. If you read old tutorials, the only real difference is the name and the mapbox to map rename of the layout key.

Tile maps need an internet connection because the tiles come from a tile server. The interactive demos below load tiles from public servers, so on a very restricted network you may see an empty gray area while the data layer still draws.

scatter_map: points on a street map

The arguments are lat, lon, and the usual color, size, hover_name, hover_data. Two layout options matter most: zoom (0 shows the whole world, 10 a city, 15 a street) and center. And map_style chooses the look.

Python Points on a map with scatter_map

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

px computes the center from your points when you do not pass center. With px.scatter_map(..., center=dict(lat=48.86, lon=2.34)) you set it yourself.

Styles without a token

The map_style option picks the base tiles:

Style Needs token? Look
"open-street-map" No Standard OSM street map
"carto-positron" No Light gray, ideal behind colored data
"carto-darkmatter" No Dark theme
"basic", "streets", "outdoors", "satellite"... Yes (Mapbox token, on the older mapbox traces) Commercial styles

For the MapLibre-based traces, the free styles above need no account at all. For commercial styles on the older mapbox traces you set px.set_mapbox_access_token("pk..."); keep tokens out of your source code and load them from an environment variable.

You can also supply your own raster tile source with a style dictionary (style="white-bg" plus layers=[...] with a tile URL), which is how some teams show an internal or historic map. Always check the license and usage policy of a tile server before using it in a production site: the free OpenStreetMap tile servers are meant for light use, so high-traffic sites should use a hosted provider.

The same map in Plotly.js

scattermap in Plotly.js

Notice that the map settings live under layout.map (older code: layout.mapbox). Pan with the mouse and zoom with the wheel; Plotly keeps the zoom and center in the figure's layout, so you can read them back from the plotly_relayout event.

Density maps: where is it busy?

With thousands of points, markers overlap into a blob. A density map (a heat map on a map) estimates how concentrated the points are and colors the area. Use px.density_map(df, lat, lon, z=..., radius=...). The optional z weights each point (for example earthquake magnitude), and radius is the blur radius in pixels, which you tune until the pattern is readable.

Python A density map of simulated pickups

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The dataset is simulated (random numbers around three centers), so no real taxi data is involved. Seeding the generator with default_rng(7) makes the output repeatable.

Region fills: choropleth_map

px.choropleth_map is the tile-map version of the choropleth: you give it a GeoJSON, a column that matches featureidkey, and a value to color. Use it instead of px.choropleth when your regions are small (districts, parcels) and the user must zoom in to street level, because the outline-map family cannot zoom that far.

Python
fig = px.choropleth_map(df, geojson=districts, locations="district_id", color="density",
                        featureidkey="properties.id", opacity=0.6, zoom=9,
                        center={"lat": 52.52, "lon": 13.40}, map_style="carto-positron")

Setting opacity below 1 lets the streets show through the colored regions.

Layers: mixing points, lines and shapes

A tile map can hold several traces: a density layer, a scattermap with mode="lines" for a route, and markers for stops. For polygons and lines drawn directly onto the map, use layout.map.layers, a list of GeoJSON layers with type ("fill", "line", "circle", "symbol"), color, opacity and source. Unlike traces, layers do not appear in the legend or on hover; they are decoration.

flowchart TD
    A["Need a map"] --> B{"Zoom to streets?"}
    B -->|No, countries and states| C["Geo family: choropleth, scattergeo"]
    B -->|Yes| D["Tile family"]
    D --> E["scatter_map: points"]
    D --> F["density_map: concentration"]
    D --> G["choropleth_map: small regions"]

Choose the geo family for outlines and the tile family when users must zoom in.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which trace names does current Plotly use for MapLibre-based tile maps?

    The mapbox names are deprecated. The new names are scattermap, densitymap and choroplethmap, configured in layout.map.
  2. 2. Which map_style needs no account or token?

    open-street-map and the carto styles use free public tiles. Commercial Mapbox styles need a token.
  3. 3. When is a density map better than markers?

    Density maps estimate concentration, so overlapping points no longer hide each other.
  4. 4. What does zoom=11 mean for a tile map?

    Zoom is the tile zoom level: 0 world, around 10 a city, 15 or more a street.

Summary

  • Tile maps (scattermap, densitymap, choroplethmap) draw your data over zoomable street tiles.
  • Free styles (open-street-map, carto-positron, carto-darkmatter) need no token; old mapbox names are deprecated.
  • Control the view with zoom and center; settings live in layout.map.
  • Use density maps for thousands of points and choropleth_map for small regions.
  • Respect tile-server usage policies and keep tokens out of source code.

Next: Hover, Click and Events