Documentation

The built-in map viewer supports drag-and-drop file visualization. Drop files directly onto the map to instantly see your data as styled overlays — with client-side parsing for lightweight formats and streaming server upload for database/raster formats.

Supported Formats

tileserver-rs supports 9 geospatial file formats, split between client-side and server-side processing:

Client-Side (parsed in the browser)

FormatExtensionsParserProcessing
GeoJSON.geojson, .jsondestr (safe JSON parse)Web Worker
CSV.csvpapaparse (lat/lng detection)Web Worker
Shapefile.zipshpjs (zero-copy transfer)Web Worker
KML.kml@tmcw/togeojsonMain thread
GPX.gpx@tmcw/togeojsonMain thread
PMTiles.pmtilespmtilesMain thread

Heavy file parsing (GeoJSON, CSV, Shapefile) runs in a dedicated web worker to keep the map UI responsive during large file processing.

Server-Side (uploaded and served as tile sources)

FormatExtensionsDescription
MBTiles.mbtilesSQLite-based vector tile archive
SQLite.sqlite, .dbTreated as MBTiles
COG.tif, .tiffCloud Optimized GeoTIFF

These formats are streamed to the server via the upload API, registered as temporary tile sources, and served back as regular vector/raster tiles.

Info

Server-side uploads require upload_dir to be configured. See Configuration for setup.

How It Works

Client-Side Flow (GeoJSON, KML, GPX, CSV, Shapefile, PMTiles)

  1. Drop a file onto the map viewer
  2. File type is detected from the extension
  3. File contents are read and sent to a web worker (or parsed on the main thread for KML/GPX/PMTiles)
  4. Parsed GeoJSON features are auto-styled with unique colors
  5. A new MapLibre source and layers are added to the map
  6. The camera auto-zooms to fit the data extent

Server-Side Flow (MBTiles, SQLite, COG)

  1. Drop a file onto the map viewer
  2. File is streamed to POST /api/upload (chunked, no full-file buffering)
  3. Server writes chunks to disk, validates the file, and registers it as a tile source
  4. Client fetches TileJSON metadata for the new source
  5. Vector layers are auto-styled and added to the map

Auto-Styling

Each dropped file gets a unique color from an 8-color palette. Layers are created based on geometry type:

  • Polygons — fill layer + outline stroke
  • LineStrings — line layer with configurable width
  • Points — circle layer with radius

Overlay Management

The overlay panel (visible after dropping files) lets you:

  • Toggle visibility — show/hide individual overlays with the eye icon
  • Remove overlays — delete overlays with the trash button (also cleans up server uploads)
  • See metadata — file name, format badge, and feature count per overlay

Configuration

Enable Server-Side Uploads

Add the following to your config.toml:

[server]
upload_dir = "/data/uploads"
upload_max_size_mb = 500
OptionDescriptionDefault
upload_dirDirectory for uploaded files-
upload_max_size_mbMaximum upload file size in MB500
Warning

Uploaded sources are session-only — they persist until deleted or the server restarts. They are not saved to the config file.

Client-Side Formats (No Config Needed)

GeoJSON, KML, GPX, CSV, Shapefile, and PMTiles files are processed entirely in the browser. No server configuration is required for these formats.

Upload API

The file drop feature uses three REST endpoints under the hood:

EndpointMethodDescription
/api/uploadPOSTUpload a file (streaming multipart)
/api/uploadGETList all uploaded sources
/api/upload/{id}DELETERemove an upload and delete the file

See the API reference for full details.

Tips

  • Large GeoJSON files are parsed in a web worker, so the map stays interactive even during multi-MB file processing
  • Shapefile uploads must be .zip archives containing .shp, .dbf, and .shx files — standalone .shp files are rejected with a helpful error message
  • CSV files need columns containing latitude and longitude values — the parser auto-detects common column names (lat, latitude, lng, longitude, lon, etc.)
  • PMTiles files are loaded directly via an object URL — no server upload needed

Next Steps