Landfall

Landfall turns geographic data into static map images with a small Python API. Plot points, routes, polygons, and circles; combine layers; or read GeoJSON and GeoPandas data. It is built on py-staticmaps by Florian Pigorsch, which supplies map tiles, framing, and rendering. Landfall keeps the native py-staticmaps API available through landfall.Context, so you can use its map objects, tile providers, context controls, and renderers directly alongside Landfall helpers. See the guide to the full py-staticmaps API. Landfall's convenience functions return Pillow images.

For geohash or H3 heatmaps from point observations, see the companion Heatfall documentation.

_{Routes · translucent areas · layered maps}

Install

Landfall supports Python 3.8–3.13. Install the optional geo extra for GeoPandas and Shapely integration.

python -m pip install landfall
python -m pip install 'landfall[geo]'  # optional
python -m pip install 'landfall[cairo]'  # optional anti-aliased PNG output

The default OpenStreetMap tile provider needs network access when rendering. If you use a different tile provider, pass a py-staticmaps provider through tile_provider or configure a Context directly. Providers that need a URL API key accept api_key= in plot functions or context.set_tile_provider(provider, api_key=...). The optional cairo extra enables anti-aliased PNG output through Context.render_cairo().

Make a map

import landfall

image = landfall.plot_points(
    [(27.88, -82.49), (27.92, -82.46), (27.94, -82.44)],
    colors="distinct",
    point_size=14,
    window_size=(640, 440),
    zoom=-1,
)
image.save("tampa-points.png")

Native coordinate pairs are (latitude, longitude). GeoJSON and Shapely positions are (longitude, latitude); Landfall converts them. For native inputs already in longitude/latitude order, use flip_coords=True.

Every plot_* function returns a PIL.Image.Image. Use Context when a map needs multiple kinds of shapes or an SVG result:

map_context = landfall.Context()
map_context.add_points([27.88, 27.92], [-82.49, -82.46], colors="distinct")
map_context.add_line([(27.88, -82.49), (27.92, -82.46)], color="red")
map_context.add_circle(27.88, -82.49, 1000, fill_color="#ff000064")
map_context.render_pillow(800, 600).save("combined.png")
map_context.render_svg(800, 600).saveas("combined.svg")

More maps you can run

route = [(27.88, -82.49), (27.90, -82.47),
         (27.92, -82.46), (27.94, -82.44)]
landfall.plot_line(
    route, color="#d12c31", width=5, window_size=(640, 440), zoom=-1
).save("route.png")

landfall.plot_circle(
    27.88, -82.49, 1000,
    color="#9b2727", fill_color="#d12c3155", width=3,
    window_size=(640, 440),
).save("coverage.png")

Circle radii are in meters by default; set radius_unit="kilometers" for kilometers. Colors can be names, hex values, RGB/RGBA tuples, or staticmaps.Color objects. Batch functions also accept the "distinct", "random", and "wheel" palettes. The checked-in images above were generated with examples/generate_doc_maps.py using real OpenStreetMap tiles; tile attribution appears in each image.

Documentation

Read the full documentation on Read the Docs.

The documentation index also links to example notebooks. For release history, see the changelog.

Support and license

Report bugs or request features through GitHub Issues. Landfall is released under the MIT license. The underlying py-staticmaps project was created by Florian Pigorsch and is also MIT licensed; see its upstream license.