Skip to content

Converting Your Data

The repo's convert-data-python/ folder has two tools for getting your data into your project's layers/: a Jupyter notebook that cleans and exports data with GeoPandas, and tippecanoe commands that turn large data into PMTiles.

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, and run the cells in order:

  1. Read and reproject the file to WGS 84 (EPSG:4326), and lowercase the column names.
  2. Keep and rename columns by listing the ones you want in keep_cols.
  3. Clean the geometry (optional): drop duplicates, simplify, remove small holes and fix invalid shapes. The meters and square meters you pass are real ones at any latitude: simplifying works in the data's local UTM zone, and hole areas are measured in an equal-area projection (EPSG:6933).
  4. Export to your project's layers/ as GeoJSON or PMTiles.

Export formats

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

For GeoParquet that other tools will read too, or that will be read remotely in parts, it's worth sorting the rows spatially and writing GeoParquet 1.1's per-row bounding box, so readers can skip chunks they don't need. It's optional; the kit doesn't need it. With GeoPandas 1.0 or later:

gdf = gdf.iloc[gdf.hilbert_distance().argsort()]
gdf.to_parquet("out.parquet", write_covering_bbox=True)

tippecanoe → PMTiles

Use tippecanoe when a GeoJSON file is too big to load whole. PMTiles only loads the tiles in view.

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

GeoJSON to PMTiles:

tippecanoe -o ../app/projects/<project>/layers/parks.pmtiles -l parks -Z 4 -z 12 parks.geojson
Flag Meaning
-o Output file (a .pmtiles name writes PMTiles)
-l Layer name inside the archive. Use it as the sourceLayer of a sourceLayers entry in layers.json
-Z / -z Lowest and highest zoom to build tiles for. Past -z, the map stretches the last level

For large or dense data, let tippecanoe pick the highest zoom and thin out crowded tiles:

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

tippecanoe can't read GeoParquet, so convert it to FlatGeobuf first:

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

Then add it as a pmtiles layer with sourceLayers: [{ sourceLayer: '<the -l name>' }]. A single-layer archive also works with sourceLayers left out.

These commands are also in convert-data-python/tippecanoe.md.