Element catalogue

One minimal example per element, with the map it produces. Every example is executed when the documentation is built, so the code shown is the code that draws the map beneath it. The gallery has larger, complete maps.

All the examples share these variables: mp (mappyng), pd, gpd, europe, regions and deps (GeoDataFrames in Lambert-93, EPSG:2154), BBOX (the mainland France frame) and DATA (the folder of the sample CSV files).

Map and Basemap

Map is the canvas: data extent, size, background. Basemap draws the context layer behind the data.

m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
)

Vector

Vector draws any geometry with a fixed style.

m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Vector(regions, fill="#fff3c4", stroke="#b45309", stroke_width=0.8)
)

Choropleth

Choropleth colours areas by a numeric column, with a classification method and a legend. See Choropleth Maps.

df = pd.read_csv(DATA / "cardio_mortalite_dep.csv", dtype={"code_dep": str})
d = deps.merge(df, left_on="COD_GEO", right_on="code_dep", how="left")
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Choropleth(d, column="taux_mortalite", cmap="Reds",
                    method="Quantiles", num_classes=5, stroke_width=0.15,
                    legend=mp.Legend("Deaths / 100,000"))
)
Deaths / 100,000 24.9 41.7 45.9 50.1 53.4 71.0 N/A

Category

Category colours areas by a qualitative column.

d = deps.copy()
d["zone"] = d["COD_GEO"].map(
    lambda c: "Overseas" if c.startswith("97") else
              "Corsica" if c.startswith("2") and c[1] in "AB" else
              "North" if c in {"59", "62", "80", "02", "60"} else "Other")
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Category(d, column="zone",
                  fill_map={"North": "#1f78b4", "Corsica": "#e31a1c",
                            "Other": "#d9d9d9"},
                  default_fill="#eeeeee",
                  legend=mp.Legend("Zone"))
)
Zone North Corsica Other Autre

Proportional

Proportional draws a circle whose area follows an absolute quantity. See Proportional Symbols.

df = pd.read_csv(DATA / "canicule_exces_75_2025.csv", dtype={"code_dep": str})
d = deps.merge(df, left_on="COD_GEO", right_on="code_dep", how="left")
pts = d[d["exces_deces"].notna()].copy()
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Vector(deps, fill="#f4f1ea", stroke="#bbbbbb", stroke_width=0.3)
    + mp.Vector(regions, stroke="#666666", stroke_width=0.6)
    + mp.Proportional(pts, column="exces_deces", fill="#d7301f",
                      fill_opacity=0.6, stroke="#7f0000",
                      legend=mp.Legend("Excess deaths"))
)
Excess deaths 72 22 1

Situation

Situation places a marker per feature, chosen by a category. See Situation (Point Symbols).

df = pd.read_csv(DATA / "helistations.csv")
pts = gpd.GeoDataFrame(
    df, geometry=gpd.points_from_xy(df["longitude"], df["latitude"]),
    crs="EPSG:4326").to_crs(2154)
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Vector(regions, fill="#f4f1ea", stroke="#999999", stroke_width=0.3)
    + mp.Situation(
        pts, column="vol_nuit",
        symbol={"Night flight": {"marker": "circle", "fill": "#1f78b4", "size": 6},
                "Day only": {"marker": "triangle", "fill": "#e31a1c", "size": 8}},
        legend=mp.Legend("Helistation"))
)
Helistation Night flight Day only

Label

Label places names automatically, avoiding overlaps. See Label Placement and the gallery example Automatic labels.

Graticule

Graticule draws meridians and parallels. See the gallery example Graticule (and The world as a globe for a globe).

Title and Source

Title (with an optional subtitle) and Source are text elements, placed by default at the top and the bottom of the map.

m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Title("Regions of France", subtitle="Mainland and Corsica")
    + mp.Source("Source: IGN GéoFLA")
)
Source: IGN GéoFLA Regions of France Mainland and Corsica

ScaleBar and NorthArrow

ScaleBar and NorthArrow. Both accept a position; see Placing elements.

m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.ScaleBar(length=200000, label="200 km", position=(0.05, 0.93))
    + mp.NorthArrow(position=(0.88, 0.1))
)
200 km N

Legend

Legend customises the legend of a thematic layer: title, orientation, decimals, swatch shape.

df = pd.read_csv(DATA / "cardio_mortalite_dep.csv", dtype={"code_dep": str})
d = deps.merge(df, left_on="COD_GEO", right_on="code_dep", how="left")
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Choropleth(d, column="taux_mortalite", cmap="Blues", num_classes=4,
                    stroke_width=0.15,
                    legend=mp.Legend("Rate", orientation="horizontal",
                                     decimals=0, swatch_shape="rounded"))
)
Rate 25 36 48 60 71 N/A

DropShadow and OceanGradient

DropShadow lifts a layer; OceanGradient lightens the water along the coasts. See Layout Elements.

m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#B9D9EB")
    + mp.OceanGradient(europe)
    + mp.Basemap()
    + mp.Vector(regions, fill="#f4f1ea", stroke="#888888", stroke_width=0.3)
    + mp.DropShadow(europe, query="code_pays_iso3 == 'FRA'")
)

Inset

Inset shows a distant area (the overseas territories) in a cartouche; Insets lays several of them out. See Layout Elements and the gallery examples Choropleth and United States with Alaska and Hawaii insets (Alaska and Hawaii).

Zoom

Zoom enlarges an area of the map in a box. Thematic layers are redrawn in the box; plain Vector layers are not. See Layout Elements and the gallery example Situation map (qualitative symbols) (Paris region).

Tooltip

Tooltip adds hover tooltips. Hover a department below. See Interactive Maps.

df = pd.read_csv(DATA / "cardio_mortalite_dep.csv", dtype={"code_dep": str})
d = deps.merge(df, left_on="COD_GEO", right_on="code_dep", how="left")
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Choropleth(d, column="taux_mortalite", cmap="Greens", num_classes=5,
                    stroke_width=0.15)
    + mp.Tooltip(["LIB_GEO", "taux_mortalite"],
                 aliases={"LIB_GEO": "Department",
                          "taux_mortalite": "Rate"})
)
24.9 34.1 43.3 52.6 61.8 71.0 N/A

BorderContrast

BorderContrast makes borders between neighbours of similar colour visible. The "check" mode reveals them in magenta.

df = pd.read_csv(DATA / "cardio_mortalite_dep.csv", dtype={"code_dep": str})
d = deps.merge(df, left_on="COD_GEO", right_on="code_dep", how="left")
m = (
    mp.Map(europe, bbox=BBOX, width=420, height="auto", facecolor="#cfe0ee")
    + mp.Basemap()
    + mp.Choropleth(d, column="taux_mortalite", cmap="Reds", num_classes=5,
                    stroke="none", border_contrast=mp.BorderContrast())
)
24.9 34.1 43.3 52.6 61.8 71.0 N/A

Tile and Raster

Tile (web map tiles) needs network access and Raster needs a GeoTIFF file, so they are not executed here: see Tile Basemaps and the Tiles example of the gallery.