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.

📖 Read the Guide → — using Starlet inside another project (CLI, Python API, embedded server) and styling the tiles with MapLibre (categorical, gradient, and label recipes, with screenshots).

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.

For worked examples — using the CLI or API inside another project, embedding the tile server, and styling the tiles with MapLibre (categorical, gradient, and label recipes) — see the Guide.

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.