GitHub - sgraaf/papermap: A Python package and CLI for creating ready-to-print paper maps.

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:

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