Skip to content

Get Started

This Get Started guide is intended as a quick way to start programming with leafmap. You can try out leafmap by using Goolge Colab (image) or Binder (image) without having to install anything on your computer.

Important Note

Leafmap has three plotting backends, including folium, ipyleaflet, and here-map-widget-for-jupyter. An interactive map created using one of the plotting backends can be displayed in a Jupyter environment, such as Google Colab, Jupyter Notebook, and JupyterLab. By default, import leafmap in Jupyter Notebook and JupyterLab will use the ipyleaflet plotting backend, whereas import leafmap in Google Colab will use the folium plotting backend. Note that Google Colab does not yet support custom widgets, such as ipyleaflet and heremap widget (source). Therefore, interactive maps created using the ipyleaflet and heremap widget backends won't show up in Google Colab, even though the code might run successfully without any errors.

The three plotting backends do not offer equal functionality. The ipyleaflet plotting backend provides the richest interactive functionality, including the custom toolset for loading, analyzing, and visualizing geospatial data interactively without coding. For example, users can add vector data (e.g., GeoJSON, Shapefile, KML, GeoDataFrame) and raster data (e.g., GeoTIFF, Cloud Optimized GeoTIFF [COG]) to the map with a few clicks (see Figure 1). Users can also perform geospatial analysis using the WhiteboxTools GUI with 468 geoprocessing tools directly within the map interface (see Figure 2). Other interactive functionality (e.g., split-panel map, linked map, time slider, time-series inspector) can also be useful for visualizing geospatial data. The ipyleaflet package is built upon ipywidgets and allows bidirectional communication between the front-end and the backend enabling the use of the map to capture user input (source). In contrast, folium has relatively limited interactive functionality. It is meant for displaying static data only. The folium plotting backend is included in this package to support using leafmap in Google Colab. Note that the aforementioned custom toolset and interactive functionality are not available for the folium plotting backend. Compared with ipyleaflet and folium, the heremap widget plotting backend provides some unique 3D functionality for visualizing geospatial data. An API key from the Here Developer Portal is required to use heremap.

Figure 1. The leafmap user interface built upon ipyleaflet and ipywidgets.

Figure 2. The WhiteboxTools graphical user interface integrated into leafmap.

To use a specific plotting backend, use one of the following:

  • import leafmap.leafmap as leafmap
  • import leafmap.foliumap as leafmap
  • import leafmap.heremap as leafmap

Leafmap Modules

The key functionality of the leafmap Python package is organized into nine modules as shown in the table below.

Module Description
basemaps A collection of XYZ and WMS tile layers to be used as basemaps
colormaps Commonly used colormaps and palettes for visualizing geospatial data
common Functions being used by multiple plotting backends to process geospatial data
foliumap A plotting backend built upon the folium Python package
heremap A plotting backend built upon the here-map-widget-for-jupyter
leafmap The default plotting backend built upon the ipyleaflet Python package
legends Built-in legends for commonly used geospatial datasets
osm Functions for extracting and downloading OpenStreetMap data
toolbar A custom toolset with interactive tools built upon ipywidgets and ipyleaflet

Launch Jupyter notebook

1
2
conda activate env_name
jupyter notebook

Use ipyleaflet plotting backend

1
2
3
import leafmap
m = leafmap.Map(center=(40, -100), zoom=4)
m

Use folium plotting backend

1
2
3
import leafmap.foliumap as leafmap
m = leafmap.Map(center=(40, -100), zoom=4)
m

Use heremap plotting backend

Prerequisites

1
export HEREMAPS_API_KEY=YOUR-ACTUAL-API-KEY

Create an interactive map

1
2
3
4
5
6
import os
import leafmap.heremap as leafmap
os.environ["HEREMAPS_API_KEY"] = "YOUR_HEREMAPS_API_KEY"
api_key = os.environ.get("HEREMAPS_API_KEY") # read api_key from environment variable.
m = leafmap.Map(api_key=api_key, center=(40, -100), zoom=4)
m

Leafmap demo with ipyleaflet backend


Last update: 2021-10-19