json-maps

Introduction

json-maps is a declarative JSON spec for interactive maps. Write JSON, get a map.

Built on MapLibre GL (free, no API key required) with CARTO basemaps and React for widgets and overlays.

Why json-maps?

Most map libraries require imperative code — initialize a map, add markers, configure layers, handle events. json-maps inverts this: you describe what you want as a JSON object, and the renderer handles the how.

This makes maps:

  • AI-friendly — LLMs can generate and stream map specs as JSON
  • Serializable — save, share, and version control your maps
  • Declarative — no imperative map API to learn
  • Reactive — change the spec, the map updates

Quick Example

{
  "basemap": "dark",
  "center": [139.69, 35.68],
  "zoom": 12,
  "pitch": 45,
  "markers": {
    "tokyo-tower": {
      "coordinates": [139.7454, 35.6586],
      "color": "#e74c3c",
      "icon": "tower-control",
      "tooltip": "Tokyo Tower · Minato",
      "popup": {
        "title": "Tokyo Tower",
        "description": "333m tall communications and observation tower"
      }
    },
    "shibuya": {
      "coordinates": [139.7013, 35.6580],
      "color": "#3498db",
      "tooltip": "Shibuya Crossing · Shibuya"
    }
  }
}

This gives you a dark-themed map centered on Tokyo with a tilted perspective and two markers with icons. Every field is optional — an empty {} gives you a light basemap at world view.

What's in the Spec

Map setup:

  • Basemap — light, dark, streets, or custom style URL
  • Viewport — center, zoom, pitch, bearing, bounds, projection

Data:

  • Markers — named pins with colors, icons, labels, tooltips, and popups
  • Layers — GeoJSON points, lines, polygons with data-driven styling and clustering
  • Heatmap — density visualization from point data
  • Routes — manual coordinate paths or auto-routed via OSRM/Mapbox

Overlays:

  • Controls — zoom, compass, fullscreen, locate
  • Legend — auto-generated from layer data-driven styles
  • Color System — continuous and categorical palettes

React API: