papermap

papermap is a Python library and CLI tool for creating ready-to-print paper maps.

Installation

papermap is available on PyPI. Install with uv or your package manager of choice:

uv add papermap

Documentation

Check out the papermap documentation for the User's Guide, API Reference and CLI Reference.

Usage

papermap can be used both in your own applications as a package, as well as a CLI tool.

As a Library

Basic Usage

Create a simple portrait-oriented, A4-sized map at scale 1:25000:

>>> from papermap import PaperMap
>>> pm = PaperMap(13.75889, 100.49722)  # Bangkok, Thailand
>>> pm.render()
>>> pm.save("Bangkok.pdf")

Custom Size and Orientation

Create a landscape-oriented, A3-sized map with grid overlay:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=40.416775,
...     lon=-3.703790,  # Madrid, Spain
...     tile_provider_key="stadia-stamenterrain",
...     size="a3",
...     landscape=True,
...     scale=50_000,
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("Madrid.pdf")

Satellite Imagery

Create a map using satellite imagery:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=51.5074,
...     lon=-0.1278,  # London, UK
...     tile_provider_key="esri-worldimagery",
...     size="a4",
...     scale=10_000,
... )
>>> pm.render()
>>> pm.save("London_Satellite.pdf")

Topographic Maps

Create a topographic map for hiking:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=46.5197,
...     lon=7.9577,  # Mürren, Switzerland
...     tile_provider_key="opentopomap",
...     size="a3",
...     landscape=True,
...     scale=25_000,
...     add_grid=True,
...     grid_size=500,  # 500m grid for easier navigation
... )
>>> pm.render()
>>> pm.save("Murren_Topo.pdf")

High-Resolution Printing

Create a high-resolution map for professional printing:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=35.6762,
...     lon=139.6503,  # Tokyo, Japan
...     tile_provider_key="openstreetmap",
...     size="a0",  # Large format
...     landscape=True,
...     scale=15_000,
...     dpi=600,  # High resolution
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("Tokyo_HighRes.pdf")

Using UTM Coordinates

Create a map using UTM coordinates instead of latitude/longitude:

>>> from papermap import PaperMap
>>> pm = PaperMap.from_utm(
...     easting=500000,
...     northing=4649776,
...     zone=30,
...     hemisphere="N",  # Northern hemisphere
...     tile_provider_key="openstreetmap",
...     size="a4",
...     scale=25_000,
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("UTM_Map.pdf")

Custom Margins

Create a map with custom margins for binding:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=-33.8688,
...     lon=151.2093,  # Sydney, Australia
...     tile_provider_key="openstreetmap",
...     size="letter",
...     margin_left=20,  # Extra margin for binding
...     margin_top=10,
...     margin_right=10,
...     margin_bottom=10,
...     scale=20_000,
... )
>>> pm.render()
>>> pm.save("Sydney_Binding.pdf")

Using API Keys

Some tile providers require API keys. Here's how to use them:

>>> from papermap import PaperMap
>>> pm = PaperMap(
...     lat=37.7749,
...     lon=-122.4194,  # San Francisco, USA
...     tile_provider_key="thunderforest-outdoors",
...     api_key="your_api_key_here",  # Get from thunderforest.com
...     size="a4",
...     landscape=True,
...     scale=25_000,
...     add_grid=True,
... )
>>> pm.render()
>>> pm.save("SF_Outdoors.pdf")

For more options and details, see the API Reference.

As a CLI Tool

Basic Usage

Create a simple portrait-oriented, A4-sized map:

$ papermap latlon -- 13.75889 100.49722 Bangkok.pdf

Custom Size and Orientation

Create a landscape-oriented, A3-sized map with grid overlay:

$ papermap latlon \
    --tile-provider stadia-stamenterrain \
    --paper-size a3 \
    --landscape \
    --scale 50000 \
    --grid \
    -- 40.416775 -3.703790 Madrid.pdf

Satellite Imagery

Create a map using satellite imagery:

$ papermap latlon \
    --tile-provider esri-worldimagery \
    --scale 10000 \
    -- 51.5074 -0.1278 London_Satellite.pdf

Topographic Maps

Create a topographic map for hiking:

$ papermap latlon \
    --tile-provider opentopomap \
    --paper-size a3 \
    --landscape \
    --scale 25000 \
    --grid \
    --grid-size 500 \
    -- 46.5197 7.9577 Murren_Topo.pdf

High-Resolution Printing

Create a high-resolution map for professional printing:

$ papermap latlon \
    --tile-provider openstreetmap \
    --paper-size a0 \
    --landscape \
    --scale 15000 \
    --dpi 600 \
    --grid \
    -- 35.6762 139.6503 Tokyo_HighRes.pdf

Using UTM Coordinates

Create a map using UTM coordinates:

$ papermap utm \
    --tile-provider openstreetmap \
    --paper-size a4 \
    --scale 25000 \
    --grid \
    -- 500000 4649776 30 N UTM_Map.pdf

Custom Margins

Create a map with custom margins for binding:

$ papermap latlon \
    --tile-provider openstreetmap \
    --paper-size letter \
    --margin-left 20 \
    --margin-top 10 \
    --margin-right 10 \
    --margin-bottom 10 \
    --scale 20000 \
    -- -33.8688 151.2093 Sydney_Binding.pdf

Using API Keys

Use tile providers that require API keys:

$ papermap latlon \
    --tile-provider thunderforest-outdoors \
    --api-key "your_api_key_here" \
    --paper-size a4 \
    --landscape \
    --scale 25000 \
    --grid \
    -- 37.7749 -122.4194 SF_Outdoors.pdf

For more options and details, see the CLI Reference.