GeoMapLib

GeoMapLib is a small, opinionated Python library for creating trustworthy and attractive geographic visualizations from Pandas and GeoPandas data.

The project is deliberately narrower than a GIS framework. GeoPandas remains the geometry engine; GeoMapLib focuses on the repetitive visualization layer: geography resolution, safe attribute joins, sensible map defaults, missing-data handling, and Matplotlib rendering.

Installation

python -m pip install geomaplib

GeoMapLib requires Python 3.12 or newer.

Quick start

The first release focuses on one job: static continuous polygon choropleths. The built-in world geography works offline and uses ISO 3166-1 alpha-3 country identifiers.

import geomaplib as gm
import pandas as pd

df = pd.DataFrame(
    {
        "iso_code": ["USA", "NGA", "TUR"],
        "value": [10.0, 25.0, 18.0],
    }
)
ax = gm.choropleth(
    data=df,
    geography="world",
    locations="iso_code",
    color="value",
)

The result is a static Matplotlib world map with the three matched countries shaded on a continuous color scale and all other polygons shown with the missing-data style. Input ISO values are stripped and uppercased; country-name matching is not performed. See the world dataset documentation for source provenance, boundary conventions, and known coverage limitations.

Custom polygon geographies can be supplied as a GeoDataFrame:

ax = gm.choropleth(
    data=df,
    geography=regions_gdf,
    feature_key="region_id",
    locations="region_id",
    color="value",
)

An existing local geography file works the same way by passing its path as geography="regions.geojson". If a GeoDataFrame already contains both its geometry and values, use gm.choropleth(data=regions_with_values, color="value") without join arguments.

choropleth() returns the exact Matplotlib Axes used for rendering, so it composes with normal Matplotlib operations:

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(10, 6))
returned = gm.choropleth(
    data=df,
    geography="world",
    locations="iso_code",
    color="value",
    ax=ax,
)
assert returned is ax
ax.set_title("Example")
fig.savefig("map.png")

Design principles

• Functional, DataFrame-first public API.
• Composition over inheritance.
• Matplotlib-native rendering and styling.
• No global plotting-style mutation.
• Exact custom-geography joins; no fuzzy matching.
• ISO alpha-3 normalization only for the built-in country geography.
• Duplicate locations never aggregate silently.
• GeoPandas and Matplotlib remain available as escape hatches.
• New abstractions are added only when new requirements justify them.

Development setup

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"

Quality checks

pytest --cov=geomaplib --cov-report=term-missing
ruff check .
ruff format --check .
mypy src/geomaplib
python -m build

Documentation

• Architecture
• Roadmap
• Boundary and identifier policy
• Built-in world geography
• Architecture decisions

v0.1 non-goals

Categorical choropleths, classification schemes, projections, point/bubble maps, labels, density maps, remote geography downloads, interactive backends, fuzzy country matching, and public Map/Layer builders are intentionally deferred. See the roadmap for the planned evolution.