The Overture Maps Explore site

The Explore Site is a web-based map viewer designed for accessible downloading of geospatial data. io-site allows for the downloading of small segments of geospatial data so that small and independent customers are able to withstand the size of the incoming data. The site also facilitates easy viewing of geospatial data by translating complex vectors and properties to a more user-friendly, readable format.

The data accessible through the site is drawn from the Overture Maps Foundation. This data is collected through open source avenues, and as such provides a free, low barrier to entry to mappers to download global data.

Participate!

• Read the project Contributing Guide to learn about how to contribute.

• See open issues in the issue tracker if you're looking to help on issues.

• The current build of the main branch is publicly available here!

• For the tilesets that power the site, see the overture-tiles repository.

For developers

Prerequisites

• Node.js (v20+)
• Volta is configured in package.json and recommended for automatic Node version management

Getting started

npm install
npm run dev

Open http://localhost:3000 in your browser.

Available scripts

Command	Description
npm run dev	Start the development server
npm run build	Build static export to out/
npm start	Start the Next.js production server
npm run preview	Serve the static export from out/ locally
npm run lint	Run ESLint
npm test	Run unit tests
npm run test:ci	Run tests in CI mode

Testing

Tests use Jest with React Testing Library and run in a jsdom environment.

npm test

Test files are located in __tests__/ and mock files for SVG and style imports are in __mocks__/.

Tech stack

• Framework: Next.js (App Router, static export)
• Mapping: MapLibre GL JS via react-map-gl
• Tiles: PMTiles served from STAC catalog
• UI: MUI (Material UI)
• Testing: Jest + React Testing Library

Deployment

• Production: Pushes to main are automatically built and deployed to GitHub Pages.
• Staging: Pull requests against main are built and deployed to an AWS S3/CloudFront staging environment.

Both workflows run linting and tests before deploying.

Project structure

app/            Next.js App Router (layout, page, global CSS)
components/     React components
  nav/          Header, download, dark mode toggle
  inspector_panel/  Feature property inspector
  navigator/    Bookmark locations
  icons/        SVG icons
lib/            Shared utilities and data
  map-styles/   MapLibre layer definitions and style variables
    variables.json   Centralized style variables (colors, fonts, sizes)
    layer-order.json Layer rendering order
    index.js         Imports all layers, resolves variable references
    addresses/       Address layer specs
    base/            Base layer specs (land, water, infrastructure, etc.)
    buildings/       Building layer specs
    divisions/       Division layer specs
    places/          Place layer specs
    transportation/  Transportation layer specs
  Layers.js     Abstract layer definitions derived from specs
  LayerManager.js  Runtime layer add/update/visibility logic
  stacService.js  STAC catalog integration
  themeUtils.js   Dark/light mode
__tests__/      Unit tests
__mocks__/      Jest mocks (SVG, styles)
public/         Static assets

Map style system

Layer styles are defined as individual JSON files in lib/map-styles/<theme>/. Each file is a valid MapLibre style layer with additional overture:* metadata.

Variables

lib/map-styles/variables.json stores shared style values in a nested theme → type → property structure:

{
  "global": {
    "colors": { "background": "...", "textHalo": "..." },
    "fonts":  { "regular": ["Noto Sans Regular"], "sizeSm": 10, "sizeMd": 11 }
  },
  "base": {
    "water":      { "color": "...", "activeColor": "...", "textColor": "...", ... },
    "land_cover": { "color": [...], ... }
  },
  ...
}

Layer JSON files reference variables with the syntax "$theme.type.property":

{
  "paint": {
    "fill-color": "$base.water.color",
    "text-color": "$base.water.textColor"
  },
  "layout": {
    "text-font": "$global.fonts.regular",
    "text-size": "$global.fonts.sizeMd"
  }
}

At import time, index.js resolves all $-references to their actual values from variables.json.

Layer IDs

Each layer's id matches its filename without .json (e.g., base/land-cover-fill.json has "id": "land-cover-fill"). The rendering order is defined in layer-order.json.

License

See the LICENSE.md file for more details.