Skip to main content

Datasette plugin that shows a cluster map for any data with latitude/longitude columns

Project description


PyPI CircleCI License

A Datasette plugin that detects tables with latitude and longitude columns and then plots them on a map using Leaflet.markercluster.

More about this project: Datasette plugins, and building a clustered map visualization

Demo hosts a demo of this plugin running against a database of 33,000 power plants around the world.

Cluster map demo


Run pip install datasette-cluster-map to add this plugin to your Datasette virtual environment. Datasette will automatically load the plugin if it is installed in this way.

If you are deploying using the datasette publish command you can use the --install option:

datasette publish cloudrun mydb.db --install=datasette-cluster-map

If any of your tables have a latitude and longitude column, a map will be automatically displayed.

If your columns are called something else you can configure the column names using plugin configuration in a metadata.json file. For example, if all of your columns are called xlat and xlng you can create a metadata.json file like this:

    "title": "Regular metadata keys can go here too",
    "plugins": {
        "datasette-cluster-map": {
            "latitude_column": "xlat",
            "longitude_column": "xlng"

Then run Datasette like this:

datasette mydata.db -m metadata.json

This will configure the required column names for every database loaded by that Datasette instance.

If you want to customize the column names for just one table in one database, you can do something like this:

    "databases": {
        "polar-bears": {
            "tables": {
                "USGS_WC_eartag_deployments_2009-2011": {
                    "plugins": {
                        "datasette-cluster-map": {
                            "latitude_column": "Capture Latitude",
                            "longitude_column": "Capture Longitude"

You can also use a custom SQL query to rename those columns to latitude and longitude, for example:

select *,
    "Capture Latitude" as latitude,
    "Capture Longitude" as longitude
from [USGS_WC_eartag_deployments_2009-2011]

Custom marker popups

The marker popup defaults to showing a formatted JSON version of the underlying database row.

You can customize this by including a popup column in your results containing JSON that defines a more useful popup.

The JSON in the popup column should look something like this:

    "image": "",
    "alt": "Dingles Fairground Heritage Centre",
    "title": "Dingles Fairground Heritage Centre",
    "description": "Home of the National Fairground Collection, Dingles has over 45,000 indoor square feet of vintage fairground rides... and you can go on them! Highlights include the last complete surviving and opera",
    "link": "/browse/museums/26"

Each of these columns is optional.

  • title is the title to show at the top of the popup
  • image is the URL to an image to display in the popup
  • alt is the alt attribute to use for that image
  • description is a longer string of text to use as a description
  • link is a URL that the marker content should link to

You can use the SQLite json_object() function to construct this data dynamically as part of your SQL query. Here's an example:

select json_object(
  'image', photo_url || '?w=800&h=400&fit=crop',
  'title', name,
  'description', substr(description, 0, 200),
  'link', '/browse/museums/' || id
  ) as popup,
  latitude, longitude from museums
where id in (26, 27) order by id

Try that example here.

How I deployed the demo

datasette publish cloudrun global-power-plants.db \
    --service global-power-plants \
    --metadata metadata.json \
    --install=datasette-cluster-map \
    --extra-options="--config facet_time_limit_ms:1000"

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for datasette-cluster-map, version 0.10
Filename, size File type Python version Upload date Hashes
Filename, size datasette_cluster_map-0.10-py3-none-any.whl (11.2 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page