Map explorer

Ever wanted to create stunning, interactive maps without dealing with servers, databases, or complicated backends? Map-explorer lets you build color coded geographic visualizations that run entirely in the browser, no server required. The best part? Fork the repository, drop in your own GeoJSON map and dataset, and you’ve got a custom interactive map you can host and share for free through GitHub Pages.

Example: Historical disease database

The live demo below shows historical disease data from Dutch newspapers between 1830-1939. You can explore how mentions of cholera, influenza, and tuberculosis changed across different regions over time.

What makes it work?

Map Explorer is a Vue.js app that combines GeoJSON maps with your datasets to create dynamic visualizations. It uses DuckDB running in WebAssembly, which means it can crunch through millions of rows of data right in your browser.

Quick start

Get up and running in three commands:

git clone https://github.com/sodascience/map-explorer.git
cd map-explorer
npm install && npm run dev

How to configure

The magic happens through simple JSON configuration files. You provide:

  1. A GeoJSON file with your map
  2. A dataset (CSV or Parquet) with values that determine the coloring of the region
  3. A config file that connects them

Here’s a minimal example:

{
  "kind": "geojson-datafile",
  "geojsonFileName": "countries.geojson",
  "dataFileName": "population.parquet",
  "idColumnGeojson": "country_code",
  "idColumnDataFile": "country_code",
  "categoryColumns": ["year"],
  "valueColumn": "population",
  "mapColorConfig": {
    "minValue": 0,
    "maxValue": 1000000,
    "colorScheme": "viridis"
  }
}

Drop your files in the /public folder, add your config to /src/config/map-configs, and you’ve got an interactive map. For the specific checkout the GitHub repository.

Deploy for Free

Want to share your map? Fork the repo, push your changes, and enable GitHub Pages. Your map will be live at yourusername.github.io/map-explorer. No hosting fees, no server management, just maps.

You can embed it like so (like we did on this page):

<iframe src="https://yourusername.github.io/map-explorer/" 
        width="100%" height="800px">
</iframe>

Multiple maps, one app

Want to show different datasets? Just add more config files to /src/config/map-configs. The app automatically creates a selector menu, letting users switch between different visualizations.

The tech behind the magic

Why does this feel so snappy compared to traditional mapping tools?

  • DuckDB-WASM: A full SQL database compiled to WebAssembly, running at near-native speed in your browser
  • Vue 3: Handles reactivity and updates efficiently
  • D3.js: Renders the maps with surgical precision
  • Parquet files: Compressed columnar format that loads fast and queries faster