1. Motivation¶
In Lesson 02, you searched for datasets and created small spatial subsets. Here, you start inspecting those data interactively.
Every visualization technique in this lesson builds on the same starting point: a leafmap map object. Getting comfortable with creating and configuring one is a small investment that pays off across the rest of the course.
2. Core idea¶
Leafmap gives you a Pythonic interface to an interactive map widget inside a Jupyter notebook. It is built on ipyleaflet but adds convenience functions for loading raster, vector, and cloud-hosted geospatial data, so you do not have to assemble those pieces yourself.
3. Create your map¶
The basic object is leafmap.Map().
import leafmap.foliumap as leafmap
m = leafmap.Map(center=[41.38, 2.16], zoom=12, height="300px") # centred near Barcelona
mThe center parameter uses a latitude-longitude pair. The zoom parameter controls how close the initial view is. The height parameter controls how much vertical space the map uses in the notebook.
4. Add basemaps¶
A Basemap gives spatial context. Without it, your results may look like shapes floating in empty space. With it, you can recognise neighbourhoods, roads, terrain or land-cover context.
m = leafmap.Map(height="300px")
m.add_basemap("Esri.WorldImagery")
mBasemap can only be one of the following: OpenStreetMap, ROADMAP, SATELLITE, TERRAIN, HYBRID, FWS NWI Wetlands, FWS NWI Wetlands Raster, NLCD 2021 CONUS Land Cover, NLCD 2019 CONUS Land Cover, NLCD 2016 CONUS Land Cover, NLCD 2013 CONUS Land Cover, NLCD 2011 CONUS Land Cover, NLCD 2008 CONUS Land Cover, NLCD 2006 CONUS Land Cover, NLCD 2004 CONUS Land Cover, NLCD 2001 CONUS Land Cover, USGS NAIP Imagery, USGS NAIP Imagery False Color, USGS NAIP Imagery NDVI, USGS Hydrography, USGS 3DEP Elevation, USGS 3DEP Elevation Index, ESA WorldCover 2020, ESA WorldCover 2020 S2 FCC, ESA WorldCover 2020 S2 TCC, ESA WorldCover 2021, ESA WorldCover 2021 S2 FCC, ESA WorldCover 2021 S2 TCC, USGS.Imagery, BaseMapDE.Color, BaseMapDE.Grey, BasemapAT.basemap, BasemapAT.grau, BasemapAT.highdpi, BasemapAT.orthofoto, BasemapAT.overlay, BasemapAT.surface, BasemapAT.terrain, CartoDB.DarkMatter, CartoDB.DarkMatterNoLabels, CartoDB.DarkMatterOnlyLabels, CartoDB.Positron, CartoDB.PositronNoLabels, CartoDB.PositronOnlyLabels, CartoDB.Voyager, CartoDB.VoyagerLabelsUnder, CartoDB.VoyagerNoLabels, CartoDB.VoyagerOnlyLabels, CyclOSM, Esri.AntarcticBasemap, Esri.AntarcticImagery, Esri.ArcticImagery, Esri.ArcticOceanBase, Esri.ArcticOceanReference, Esri.NatGeoWorldMap, Esri.OceanBasemap, Esri.WorldGrayCanvas, Esri.WorldPhysical, Esri.WorldShadedRelief, Esri.WorldTerrain, FreeMapSK, Gaode.Normal, Gaode.Satellite, HikeBike.HikeBike, HikeBike.HillShading, JusticeMap.americanIndian, JusticeMap.asian, JusticeMap.black, JusticeMap.hispanic, JusticeMap.income, JusticeMap.multi, JusticeMap.nonWhite, JusticeMap.plurality, JusticeMap.white, MtbMap, NASAGIBS.ASTER_GDEM_Greyscale_Shaded_Relief, NASAGIBS.BlueMarble, NASAGIBS.BlueMarble3031, NASAGIBS.BlueMarble3413, NASAGIBS.BlueMarbleBathymetry3031, NASAGIBS.BlueMarbleBathymetry3413, NASAGIBS.MEaSUREsIceVelocity3031, NASAGIBS.MEaSUREsIceVelocity3413, NASAGIBS.ModisAquaBands721CR, NASAGIBS.ModisAquaTrueColorCR, NASAGIBS.ModisTerraAOD, NASAGIBS.ModisTerraBands367CR, NASAGIBS.ModisTerraBands721CR, NASAGIBS.ModisTerraChlorophyll, NASAGIBS.ModisTerraLSTDay, NASAGIBS.ModisTerraSnowCover, NASAGIBS.ModisTerraTrueColorCR, NASAGIBS.ViirsEarthAtNight2012, NASAGIBS.ViirsTrueColorCR, OPNVKarte, OneMapSG.Default, OneMapSG.Grey, OneMapSG.LandLot, OneMapSG.Night, OneMapSG.Original, OpenAIP, OpenFireMap, OpenRailwayMap, OpenSeaMap, OpenSnowMap.pistes, OpenStreetMap.BZH, OpenStreetMap.CAT, OpenStreetMap.CH, OpenStreetMap.DE, OpenStreetMap.HOT, OpenStreetMap.Mapnik, OpenTopoMap, SafeCast, Stadia.AlidadeSatellite, Stadia.AlidadeSmooth, Stadia.AlidadeSmoothDark, Stadia.OSMBright, Stadia.Outdoors, Stadia.StamenTerrain, Stadia.StamenTerrainBackground, Stadia.StamenTerrainLabels, Stadia.StamenTerrainLines, Stadia.StamenToner, Stadia.StamenTonerBackground, Stadia.StamenTonerBlacklite, Stadia.StamenTonerDark, Stadia.StamenTonerLabels, Stadia.StamenTonerLines, Stadia.StamenTonerLite, Stadia.StamenWatercolor, Strava.All, Strava.Ride, Strava.Run, Strava.Water, Strava.Winter, SwissFederalGeoportal.JourneyThroughTime, SwissFederalGeoportal.NationalMapColor, SwissFederalGeoportal.NationalMapGrey, SwissFederalGeoportal.SWISSIMAGE, TopPlusOpen.Color, TopPlusOpen.Grey, UN.ClearMap, USGS.USImagery, USGS.USImageryTopo, USGS.USTopo, WaymarkedTrails.cycling, WaymarkedTrails.hiking, WaymarkedTrails.mtb, WaymarkedTrails.riding, WaymarkedTrails.skating, WaymarkedTrails.slopes, nlmaps.grijs, nlmaps.luchtfoto, nlmaps.pastel, nlmaps.standaard, nlmaps.water
Different basemaps support different purposes.
| Basemap type | Useful for |
|---|---|
| Satellite imagery | Checking labels or predictions against visible ground features. |
| Street map | Orienting readers with roads, places and neighbourhood names. |
| Terrain map | Understanding elevation, relief or hydrological context. |
| Light neutral map | Presenting thematic layers without visual clutter. |
You can also add more than one basemap and switch between them with the layer control.
m = leafmap.Map(height="300px")
m.add_basemap("Esri.WorldImagery")
m.add_basemap("OpenTopoMap")
mBasemap can only be one of the following: OpenStreetMap, ROADMAP, SATELLITE, TERRAIN, HYBRID, FWS NWI Wetlands, FWS NWI Wetlands Raster, NLCD 2021 CONUS Land Cover, NLCD 2019 CONUS Land Cover, NLCD 2016 CONUS Land Cover, NLCD 2013 CONUS Land Cover, NLCD 2011 CONUS Land Cover, NLCD 2008 CONUS Land Cover, NLCD 2006 CONUS Land Cover, NLCD 2004 CONUS Land Cover, NLCD 2001 CONUS Land Cover, USGS NAIP Imagery, USGS NAIP Imagery False Color, USGS NAIP Imagery NDVI, USGS Hydrography, USGS 3DEP Elevation, USGS 3DEP Elevation Index, ESA WorldCover 2020, ESA WorldCover 2020 S2 FCC, ESA WorldCover 2020 S2 TCC, ESA WorldCover 2021, ESA WorldCover 2021 S2 FCC, ESA WorldCover 2021 S2 TCC, USGS.Imagery, BaseMapDE.Color, BaseMapDE.Grey, BasemapAT.basemap, BasemapAT.grau, BasemapAT.highdpi, BasemapAT.orthofoto, BasemapAT.overlay, BasemapAT.surface, BasemapAT.terrain, CartoDB.DarkMatter, CartoDB.DarkMatterNoLabels, CartoDB.DarkMatterOnlyLabels, CartoDB.Positron, CartoDB.PositronNoLabels, CartoDB.PositronOnlyLabels, CartoDB.Voyager, CartoDB.VoyagerLabelsUnder, CartoDB.VoyagerNoLabels, CartoDB.VoyagerOnlyLabels, CyclOSM, Esri.AntarcticBasemap, Esri.AntarcticImagery, Esri.ArcticImagery, Esri.ArcticOceanBase, Esri.ArcticOceanReference, Esri.NatGeoWorldMap, Esri.OceanBasemap, Esri.WorldGrayCanvas, Esri.WorldPhysical, Esri.WorldShadedRelief, Esri.WorldTerrain, FreeMapSK, Gaode.Normal, Gaode.Satellite, HikeBike.HikeBike, HikeBike.HillShading, JusticeMap.americanIndian, JusticeMap.asian, JusticeMap.black, JusticeMap.hispanic, JusticeMap.income, JusticeMap.multi, JusticeMap.nonWhite, JusticeMap.plurality, JusticeMap.white, MtbMap, NASAGIBS.ASTER_GDEM_Greyscale_Shaded_Relief, NASAGIBS.BlueMarble, NASAGIBS.BlueMarble3031, NASAGIBS.BlueMarble3413, NASAGIBS.BlueMarbleBathymetry3031, NASAGIBS.BlueMarbleBathymetry3413, NASAGIBS.MEaSUREsIceVelocity3031, NASAGIBS.MEaSUREsIceVelocity3413, NASAGIBS.ModisAquaBands721CR, NASAGIBS.ModisAquaTrueColorCR, NASAGIBS.ModisTerraAOD, NASAGIBS.ModisTerraBands367CR, NASAGIBS.ModisTerraBands721CR, NASAGIBS.ModisTerraChlorophyll, NASAGIBS.ModisTerraLSTDay, NASAGIBS.ModisTerraSnowCover, NASAGIBS.ModisTerraTrueColorCR, NASAGIBS.ViirsEarthAtNight2012, NASAGIBS.ViirsTrueColorCR, OPNVKarte, OneMapSG.Default, OneMapSG.Grey, OneMapSG.LandLot, OneMapSG.Night, OneMapSG.Original, OpenAIP, OpenFireMap, OpenRailwayMap, OpenSeaMap, OpenSnowMap.pistes, OpenStreetMap.BZH, OpenStreetMap.CAT, OpenStreetMap.CH, OpenStreetMap.DE, OpenStreetMap.HOT, OpenStreetMap.Mapnik, OpenTopoMap, SafeCast, Stadia.AlidadeSatellite, Stadia.AlidadeSmooth, Stadia.AlidadeSmoothDark, Stadia.OSMBright, Stadia.Outdoors, Stadia.StamenTerrain, Stadia.StamenTerrainBackground, Stadia.StamenTerrainLabels, Stadia.StamenTerrainLines, Stadia.StamenToner, Stadia.StamenTonerBackground, Stadia.StamenTonerBlacklite, Stadia.StamenTonerDark, Stadia.StamenTonerLabels, Stadia.StamenTonerLines, Stadia.StamenTonerLite, Stadia.StamenWatercolor, Strava.All, Strava.Ride, Strava.Run, Strava.Water, Strava.Winter, SwissFederalGeoportal.JourneyThroughTime, SwissFederalGeoportal.NationalMapColor, SwissFederalGeoportal.NationalMapGrey, SwissFederalGeoportal.SWISSIMAGE, TopPlusOpen.Color, TopPlusOpen.Grey, UN.ClearMap, USGS.USImagery, USGS.USImageryTopo, USGS.USTopo, WaymarkedTrails.cycling, WaymarkedTrails.hiking, WaymarkedTrails.mtb, WaymarkedTrails.riding, WaymarkedTrails.skating, WaymarkedTrails.slopes, nlmaps.grijs, nlmaps.luchtfoto, nlmaps.pastel, nlmaps.standaard, nlmaps.water
5. Inspect available basemaps¶
Leafmap provides many basemap options. You do not need to memorise them. You can inspect the list when needed.
basemaps = list(leafmap.basemaps.keys())
print(f"Total basemaps: {len(basemaps)}")
print("First 10:", basemaps[:10])Total basemaps: 156
First 10: ['OpenStreetMap', 'ROADMAP', 'SATELLITE', 'TERRAIN', 'HYBRID', 'FWS NWI Wetlands', 'FWS NWI Wetlands Raster', 'NLCD 2021 CONUS Land Cover', 'NLCD 2019 CONUS Land Cover', 'NLCD 2016 CONUS Land Cover']
Use this list to test basemaps for your project map. Choose one that helps interpretation rather than one that simply looks attractive.
6. Use maps as a project check¶
For your own project, a first map should answer three basic questions:
Is the map centred on the right place?
Is the zoom level appropriate for the feature or pattern?
Does the basemap help interpret the area?
If the answer to any of these is unclear, fix the map before adding more layers.
7. Python reactivation¶
leafmap.Map() returns an object, and you build up your visualization by calling methods on that object (m.add_basemap(...)) rather than reassigning m each time. This is the same pattern you used with matplotlib axes objects in SDS210: create the object once, then call methods on it to add more content.
8. Common pitfalls¶
| Pitfall | How to avoid it |
|---|---|
| The map opens in the wrong place | Check whether coordinates are latitude-longitude or longitude-latitude. |
| The basemap distracts from the data | Use a simpler basemap or reduce layer opacity. |
| The map is too zoomed out | Match zoom level to the feature size you need to inspect. |
| Too many layers are added at once | Build the map gradually and check each layer. |
| Layer names are unclear | Use descriptive names that explain what each layer shows. |
9. Mini task¶
Create a map centered on your own project’s rough study area (or a placeholder location if you do not have one yet). Add two different basemaps to it and use the layer control to switch between them.
Note
Sample solution
import leafmap.foliumap as leafmap
m = leafmap.Map(center=[46.0637, 8.3579], zoom=12, height="500px")
m.add_basemap("Esri.WorldTerrain")
m.add_basemap("SwissFederalGeoportal.SWISSIMAGE")
mSwitching between “Esri.WorldImagery” and “OpenTopoMap” in the layer control shows the same area once as satellite imagery and once as a topographic map, which is a quick way to decide which basemap best supports your project’s study area.
---
## 10. Key takeaways
- Leafmap creates interactive maps directly in notebooks.
- Basemaps provide spatial context for data inspection.
- Map centres use latitude-longitude order.
- Interactive maps are useful for debugging and project decisions, not only final presentation.
- Start simple before adding raster, vector or model layers.