Skip to content

GeoParquet, DuckDB and Python

manby reads GeoParquet and Arrow files directly, and its Python package tiles DuckDB queries, GeoDataFrames, and Polars and PyArrow tables. The tiles are the ones tippecanoe makes from the same features as FlatGeobuf.

Terminal window
manby -zg --drop-densest-as-needed -o buildings.pmtiles buildings.parquet

Arrow IPC files and streams, .arrow, .arrows and .feather, read the same way.

  • Geometry. The column that the GeoParquet metadata names, or the first with a GeoArrow type, or a column named geometry in well-known binary. Rows without a geometry are left out.
  • Coordinates. In the CRS that the GeoParquet or GeoArrow metadata names: longitude and latitude, Web Mercator, or any of the 9,508 EPSG and ESRI codes of crs-defs, which are made longitude and latitude within centimeters of PROJ. Without a CRS, -s names it.
  • Attributes. Each field of a struct becomes an attribute of its own, such as names.primary, and lists and maps become JSON text, as GDAL makes them. Dates and times become ISO 8601 text, with a Z for UTC where they have a zone. Binary columns are left out.

In GeoJSON, a feature’s tippecanoe object says which zooms it shows at. A table has no such object, so two options take the zooms from columns.

Terminal window
manby -z14 --use-attribute-for-minzoom=shows_from -o roads.pmtiles roads.parquet
  • --use-attribute-for-minzoom=NAME takes the lowest zoom a feature shows at, and --use-attribute-for-maxzoom=NAME the highest.
  • Values. Whole numbers from 0 to 32. A row without a value shows at every zoom. Any other value stops the run, and -T shows_from:int makes text a number first.
  • Attributes. The columns are the zooms now, and are not kept as attributes.
  • Inputs. Every format takes them, FlatGeobuf, CSV and the properties of GeoJSON as well.
  • Tiles. The ones tippecanoe makes of the same features as GeoJSON, with these zooms in their tippecanoe objects.

From Python the option is use_attribute_for_minzoom="shows_from", and a DuckDB query can work the zooms out.

A URL reads GeoParquet in place: one file, a prefix ending in /, or a glob, whose files are read in the order of their names as one table. Only the row groups that --bbox may overlap are fetched, by byte range, so a city out of a planet takes seconds.

Terminal window
manby -zg --drop-densest-as-needed --bbox=13.08,52.33,13.76,52.68 -o berlin.pmtiles \
's3://overturemaps-us-west-2/release/2026-10-21.0/theme=places/type=place/*'

That reads 29 of the 6,144 row groups of Overture’s places, 12 GB in 16 files, in 6 to 25 seconds from Europe. The layer is named after the last part of the path, here place.

  • URLs. s3://, gs://, az:// and https://. Credentials come from the environment, as AWS_ACCESS_KEY_ID or GOOGLE_APPLICATION_CREDENTIALS. Without them, requests go unsigned, as public buckets take them, and an S3 bucket’s region is looked up unless AWS_REGION gives it.
  • --bbox=minlon,minlat,maxlon,maxlat keeps the rows whose geometries’ bounding boxes overlap it, from local files as well. The row groups come from the statistics of GeoParquet 1.1 bounding box columns, or of Parquet’s own geospatial statistics. The tiles are those of the table of the rows kept.
  • Builds. The releases, pip, Homebrew and R read URLs. Built with cargo, it needs --features remote.

pip install manby also installs the manby module. manby.tile takes the input, the tileset to write, and tippecanoe’s options.

import manby
manby.tile("buildings.parquet", "buildings.pmtiles", "-zg", "--drop-densest-as-needed")

The options can be keywords too, named as tippecanoe’s long options, with True for a flag and a list to repeat one.

manby.tile(
"buildings.parquet",
"buildings.pmtiles",
maximum_zoom="g",
drop_densest_as_needed=True,
include=["height", "class"],
)

An existing tileset is overwritten, unless force=False. If manby fails, manby.ManbyError has tippecanoe’s exit status.

A DuckDB query goes in as it is. Its result streams to manby in Arrow batches, so it need not fit in memory.

import duckdb, manby
con = duckdb.connect()
con.sql("LOAD spatial")
roads = con.sql("""
SELECT name, class, geometry
FROM 'roads.parquet'
WHERE class IN ('motorway', 'trunk', 'primary')
""")
manby.tile(roads, "roads.pmtiles", layer="roads", maximum_zoom=14)

The query can also work out the zoom each row shows from, for use_attribute_for_minzoom.

roads = con.sql("""
SELECT name, class, geometry,
CASE class WHEN 'motorway' THEN 5 WHEN 'trunk' THEN 7 ELSE 10 END AS shows_from
FROM 'roads.parquet'
""")
manby.tile(
roads,
"roads.pmtiles",
layer="roads",
maximum_zoom=14,
use_attribute_for_minzoom="shows_from",
)

A GeoDataFrame in another CRS is reprojected to WGS 84 first. A file in a format that manby does not read, such as KML, GPX or OpenStreetMap, is read with GeoPandas, or with DuckDB if GeoPandas is not installed. See Other formats. h3_sql gives the hexagons of --h3 aggregates written in DuckDB’s SQL, as in Aggregates in SQL.

import geopandas, manby
counties = geopandas.read_file("counties.gpkg")
manby.tile(
counties,
"counties.pmtiles",
layer="counties",
maximum_zoom="g",
coalesce_densest_as_needed=True,
)

Polars and PyArrow tables go in the same way, as does anything else with an Arrow stream, with the geometry in a GeoArrow column or in a column named geometry in well-known binary.

A dict names the layers, each a table or a file.

manby.tile({"roads": roads, "places": "places.parquet"}, "map.pmtiles", maximum_zoom=14)

manby.serve serves tilesets with a map of them, in a browser or in a notebook, and manby.stats reports their tiles’ sizes and features. Looking at tilesets has more.

server = manby.serve("roads.pmtiles")
server.stop()

manby.run runs manby with arguments as on the command line, such as manby join.

manby.run("join", "-o", "map.pmtiles", "roads.pmtiles", "places.pmtiles")