Starlet

Turn large geospatial datasets into fast, interactive maps. Starlet partitions a GeoParquet / GeoJSON file into spatial tiles, generates Mapbox Vector Tiles, and serves them over HTTP with a built-in web viewer — all from a single command-line tool.

Install

pip install starlet

Requires Python 3.10+. On systems where pip points at Python 2, use pip3:

pip3 install starlet

This installs the starlet command-line tool. Check it:

starlet --version

Quick start

Go from a data file to a live map in two commands:

# 1. Build a dataset: partition into tiles + pre-generate vector tiles
starlet build --input data.parquet --outdir datasets/mydata

# 2. Serve it
starlet serve --dir datasets --port 8765

Open http://localhost:8765 and pick your dataset to explore it on a map.

Commands

Everything runs through the starlet CLI. Run starlet <command> --help for the full option list.

The options you'll actually use

Examples

# Build to a deeper zoom (more detail when you zoom in)
starlet build --input roads.parquet --outdir datasets/roads --zoom 12

# GeoJSON input, custom geometry column
starlet build --input places.geojson --outdir datasets/places --geom-col wkb_geometry

# Serve a whole folder of datasets; the viewer lists them all
starlet serve --dir datasets --port 8765

# Inspect what got built
starlet info --dir datasets/roads

Input formats

Starlet reads GeoParquet, GeoJSON, and CSV (with either x/y columns or a WKT column — see starlet tile --help). Source data is assumed to be longitude/latitude (EPSG:4326); tiles are produced in Web Mercator (EPSG:3857).

One-file distribution with PMTiles

Pass --pmtiles to pack every generated tile into a single PMTiles archive — handy for shipping a dataset as one file or hosting it on static storage:

starlet build --input data.parquet --outdir datasets/mydata --pmtiles

Server API

While starlet serve is running:

Tiles are served in tiers — an in-memory LRU cache, then a pre-generated PMTiles archive or .mvt files on disk, then generated on the fly from the Parquet tiles when you zoom past the pre-built levels — so you can serve a dataset even without pre-generating every zoom.

Configuration

Settings you reuse often (partition size, zoom, worker count, …) can live in a starlet.toml file instead of being passed on every command. Copy starlet.toml.example to starlet.toml and edit it; Starlet loads it automatically. CLI flags always override the file. See docs/CONFIGURATION.md for the full list of keys.

Deploying a server

docs/DEPLOYMENT.md walks through standing up a production tile server, including a no-root recipe behind an existing Apache install.

Using Starlet from Python

starlet is also importable — tile(), generate_mvt(), build(), export_pmtiles(), and create_app() are documented in docs/PUBLIC_API.md.

Want to work on Starlet itself — run it from a clone, run the tests, or contribute a change? See DEVELOPMENT.md.

License

Starlet is distributed under the MIT License.