Declarative Maps from JSON

AI → JSON → Map

Describe an interactive map as JSON, get markers, routes, layers, and data visualization. AI-ready specs with guardrailed components.

npm install json-maps

Playground Docs GitHub

Define Your Map Spec

Describe viewport, layers, markers, routes, and data sources as a JSON spec. Every property is typed and validated.

AI Generates

Describe what you want in natural language. AI generates a map spec constrained to your catalog of layers and components.

Render the Map

One component renders it all. Stream the response and watch markers, routes, and layers appear progressively.

Write a map spec

Viewport, markers, routes, layers, controls — all as JSON.

{
  "center": [-73.98, 40.75],
  "zoom": 12,
  "layers": {
    "cafes": {
      "type": "geojson",
      "data": "https://data.city/cafes.geojson",
      "cluster": true,
      "clusterOptions": {
        "radius": 50,
        "colors": ["#22c55e", "#eab308", "#ef4444"]
      }
    }
  },
  "markers": {
    "home": {
      "coordinates": [-73.98, 40.75],
      "label": "Home",
      "popup": { "title": "My Location" }
    }
  },
  "controls": {
    "zoom": true,
    "compass": true
  }
}

Render it

One component. One spec. Interactive map.

import { MapRenderer } from "json-maps";

const spec = {
  center: [-73.98, 40.75],
  zoom: 12,
  layers: {
    cafes: {
      type: "geojson",
      data: "https://data.city/cafes.geojson",
      cluster: true,
    },
  },
  markers: {
    home: {
      coordinates: [-73.98, 40.75],
      label: "Home",
    },
  },
  controls: { zoom: true, compass: true },
};

export default function MyMap() {
  return <MapRenderer spec={spec} />;
}

Data-driven layers

Choropleth, heatmap, fill, and circle layers with color scales and legends — all from JSON.

{
  "layers": {
    "population": {
      "type": "geojson",
      "data": "https://data.gov/states.geojson",
      "style": {
        "fillColor": {
          "type": "continuous",
          "attr": "population",
          "palette": "Sunset",
          "domain": [0, 40000000]
        },
        "opacity": 0.7
      },
      "tooltip": ["name", "population"]
    }
  },
  "legend": {
    "pop": {
      "layer": "population",
      "title": "Population"
    }
  }
}

Actions & interactions

React callbacks for marker clicks, drags, viewport changes, and layer clicks. Full control over interactions.

import { MapRenderer } from "json-maps";

<MapRenderer
  spec={spec}
  onMarkerClick={(id, coords) => {
    console.log("Clicked:", id, coords);
  }}
  onViewportChange={(viewport) => {
    setSpec(prev => ({ ...prev, ...viewport }));
  }}
  onMarkerDragEnd={(id, coords) => {
    updateMarkerPosition(id, coords);
  }}
  onLayerClick={(layerId, coords) => {
    showFeatureDetails(layerId, coords);
  }}
/>

Features

Declarative Specs

Describe an entire interactive map as JSON. Viewport, layers, markers, routes, controls, legends.

Data Layers

Choropleth, heatmap, clusters, fill, and circle layers with data-driven color scales.

Streaming

Progressive rendering as JSON streams from AI. Watch markers and layers appear in real time.

AI-Ready

Define a catalog of map components. AI generates specs constrained to your catalog.

MapLibre Powered

Built on MapLibre GL. Open source, no API keys required. Full access to the underlying map.

Interactions

Marker click, drag, viewport change, and layer click callbacks. Controlled viewport with onViewportChange.

Get started

npm install json-maps

Try the Playground Documentation