Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

datasette-maplibre

PyPI Changelog Tests License

Datasette plugin that maps latitude/longitude and GeoJSON data using MapLibre GL and OpenFreeMap.

It combines the features of datasette-cluster-map and datasette-leaflet-geojson on a vector map, and adds some of its own.

Demo

Try the demo instance, which runs in your browser using Datasette Lite.

Its home page is a guided tour of every feature: 19 links, each opening a map set up to show one thing. It uses 35,000 power plants, a month of earthquakes, country boundaries, rivers, capital cities and landmarks with photographs.

To run the same demo locally, use the demo/ directory:

uv run python demo/build.py
uv run datasette demo/demo.db -m demo/metadata.yml -c demo/datasette.yml --setting max_returned_rows 5000

build.py downloads about 14MB of open data to demo/cache/ the first time it runs, then builds demo/demo.db. Run it with --refresh to fetch the data again, for example for more recent earthquakes.

Installation

Install this plugin in the same environment as Datasette. It requires Datasette 1.0a43 or later.

datasette install datasette-maplibre

MapLibre GL JS 6.17.0 is bundled with the plugin. Map styles, tiles and fonts are loaded from tiles.openfreemap.org unless you configure a different style.

Usage

An overview map above the table

A map is shown above any table, SQL query or row that has one of these pairs of columns:

  • latitude and longitude
  • lat and lng, lon or long
  • *_latitude and *_longitude
  • *_lat and *_lng, *_lon or *_long

It is also shown for tables and queries with several rows of GeoJSON, in which case every shape is drawn on the one map. A table with both gets points and shapes together.

Rows are loaded from the Datasette JSON API. If there are more rows than fit in one page a "load all" button fetches the rest, with a "pause" button to stop. The map is added to the page once the first row with a location has loaded.

The toolbar above the map offers:

  • View - clusters, individual points or a heatmap
  • Colour by - colour the points and shapes by any column. Columns with up to ten distinct values get a legend with counts, numeric columns with more get a colour ramp.
  • Globe - switch between a globe and a flat map
  • Filter to this area - on table pages, reloads the table with filters such as ?latitude__gte=... so that it only contains rows inside the area the map is showing. "Clear area filter" removes them.
  • Download GeoJSON - everything loaded onto the map so far, as a GeoJSON file with the other columns as properties

The map also has zoom, compass and fullscreen controls. To tilt it into 3D, drag with the right mouse button or with ctrl held down: zoom in to a city to see the buildings.

Other things to know:

  • Clicking a point or shape shows a popup with the row, and highlights that row in the table if it is on the current page.
  • Hovering over a table row highlights its point or shape on the map.
  • The map shows every row, where the table shows one page of them. When the map has more, the line under it says "All 171 rows are on the map".
  • Shapes that are too small to see at the current zoom level are marked with a circle.
  • The position of the map is kept in the URL, as #map=zoom/latitude/longitude, so a link to the page is a link to that view of the map. So are the view, colour and globe when they differ from the configured ones: #view=heatmap&color=fuel&globe=1. These can be used in links you write yourself.
  • The map never zooms out so far that the world is repeated side by side.
  • Scrolling the page does not zoom the map. Use ctrl + scroll (⌘ + scroll on macOS), or the zoom buttons.

A map for every GeoJSON value

Any table cell containing GeoJSON - a geometry, a Feature or a FeatureCollection - is replaced by a map of it.

Each cell first gets an outline of its geometry drawn as SVG, which is instant. Cells then turn into interactive maps as they scroll into view. Browsers limit how many WebGL maps a page can have, so only eight cells are live maps at once: when a ninth is needed, the oldest one that is off screen goes back to being an outline. This means a page with hundreds of shapes works.

Custom popups

The popup defaults to displaying the row. Include a popup column containing JSON to replace it:

select json_object(
  'image', photo_url,
  'alt', 'Photo of ' || name,
  'title', name,
  'description', substr(description, 0, 200),
  'link', '/browse/museums/' || id
) as popup, latitude, longitude from museums

Every key is optional. This is the same format that datasette-cluster-map uses. link and image must be http://, https:// or relative URLs.

Configuration

All of these are optional. They can be set for the whole instance, for a database or for a table, and more specific settings are merged over more general ones.

{
    "plugins": {
        "datasette-maplibre": {
            "latitude_column": "xlat",
            "longitude_column": "xlng",
            "style": "https://example.com/style.json",
            "view": "points",
            "color_column": "category",
            "height": "70vh",
            "scroll_zoom": true,
            "max_cell_maps": 12,
            "cluster_radius": 50,
            "container": "#map-goes-here"
        }
    }
}
  • latitude_column and longitude_column - the columns to use, if they do not match the patterns above
  • style - the URL of a MapLibre style, or a complete style as a JSON object. Defaults to the OpenFreeMap Liberty style, https://tiles.openfreemap.org/styles/liberty.
  • view - clusters (the default), points or heatmap
  • color_column - a column to colour by to begin with
  • height - CSS height of the overview map, default 500px
  • scroll_zoom - set to true to zoom the overview map with the scroll wheel alone
  • max_cell_maps - how many GeoJSON cells can be interactive maps at once, default 8
  • cluster_radius - how close points have to be, in pixels, to be merged into one cluster. Default 25. Smaller values give more, smaller clusters.
  • container - CSS selector of an element to add the overview map to, instead of above the table

The MapLibre map object for the overview map is available to other JavaScript as datasette.maplibre.map.

Development

To set up this plugin locally, first checkout the code. Then run the tests using uv:

cd datasette-maplibre
uv run pytest

Some of the tests use Playwright to drive a real browser. They use an empty map style, so they do not need to fetch any tiles. If they fail because the browser is missing, install it like this:

uv run playwright install chromium

To update MapLibre GL JS, replace maplibre-gl.mjs, maplibre-gl-worker.mjs and maplibre-gl.css in datasette_maplibre/static/ with the files from the dist/ directory of the maplibre-gl npm package. The two .mjs files must stay next to each other.

Metadata

Release files for datasette-maplibre 0.1a0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for datasette-maplibre 0.1a0
File Size Uploaded Provenance Actions
datasette_maplibre-0.1a0.tar.gz 491.1 kB With provenance Details for datasette_maplibre-0.1a0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for datasette-maplibre 0.1a0
File Interpreter ABI Platform Actions
datasette_maplibre-0.1a0-py3-none-any.whl Python 3 none any Details for datasette_maplibre-0.1a0-py3-none-any.whl

Total release size: 975.7 kB

Release files / datasette_maplibre-0.1a0.tar.gz

Download URL datasette_maplibre-0.1a0.tar.gz
Size 491.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7cd53e830d1d65002bc7a6c0a889ef3c912d2ac83bd2d4cfbafbc3b35b970404
BLAKE2b-256 checksum
How to use checksums
7b445cf42d81fcb69efee67c850b2485003fc67e3100f10f1be7c3372f360993
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / datasette_maplibre-0.1a0-py3-none-any.whl

Download URL datasette_maplibre-0.1a0-py3-none-any.whl
Size 484.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d34030aeafaed41d38073361e1d9f939911307d073bbe7cc98627b11202cfe3
BLAKE2b-256 checksum
How to use checksums
b49d43498f16f86c128a27af275233f2ae1aea6f7c9f37f980d5d02bd10e3131
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for datasette-maplibre 0.1a0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for datasette_maplibre-0.1a0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page