Skip to content

Converting Your Data

The repo's convert-data-python/ folder holds two tools for getting your own data into app/layers/: a Jupyter notebook for cleaning and exporting with GeoPandas, and tippecanoe commands for building PMTiles from large data.

The notebook

cd convert-data-python
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Open convert-data.ipynb in VS Code, set in_file_path and output_layer_name in the first cell, then run top to bottom:

  1. Read + reproject the file to WGS 84 (EPSG:4326) and lowercase the column names.
  2. Keep + rename columns — list the ones you want in keep_cols.
  3. Clean geometry (optional) — drop duplicates, simplify, remove small holes, fix invalid shapes.
  4. Export to app/layers/ as GeoJSON or PMTiles.

Export formats

The notebook writes GeoJSON and PMTiles only. For FlatGeobuf or GeoParquet, use GeoPandas directly (gdf.to_file('out.fgb'), gdf.to_parquet('out.parquet')).

tippecanoe → PMTiles

Use tippecanoe when a GeoJSON is too large to load whole — PMTiles streams only the tiles in view.

brew install tippecanoe gdal   # other OSes: see the tippecanoe README

GeoJSON → PMTiles:

tippecanoe -o ../app/layers/parks.pmtiles -l parks -Z 4 -z 12 parks.geojson
Flag Meaning
-o Output file (.pmtiles writes PMTiles)
-l Layer name inside the archive — use it as sourceLayer in layers.ts
-Z / -z Min / max zoom to build tiles for. Past -z the map overzooms the last level

Large or dense data — let tippecanoe pick the max zoom and thin crowded tiles:

tippecanoe -o ../app/layers/buildings.pmtiles -l buildings -zg --drop-densest-as-needed buildings.geojson

GeoParquet → PMTiles — tippecanoe can't read Parquet, so convert to FlatGeobuf first:

ogr2ogr roads.fgb roads.parquet
tippecanoe -o ../app/layers/roads.pmtiles -l roads -Z 6 -z 14 roads.fgb

Then add it as a pmtiles layer with sourceLayer set to the -l name.

The same commands live in convert-data-python/tippecanoe.md.