Welcome to iXMaps Documentation

iXMaps defines a high-level visualization grammar for thematic maps. It provides a concise JSON syntax for supporting rapid generation of visualizations from raw data — operating directly in the browser with no installation and no build step.

Map 1: World GDP per capita, 2023 –> fullscreen

What is iXMaps?

At its core, iXMaps theme specifications are JSON objects that describe visualizations as mappings from data to properties of geographical map objects. The framework combines:

  • Visualization grammar - Declarative JSON layer definitions: data → binding → type → style
  • Interactive Mapping - SVG-based maps with zoom, pan, and search capabilities
  • Data Processing - Advanced data manipulation with Data.js library
  • Visualization Themes - Choropleth, bubble charts, symbols, and custom visualizations
  • Real-time Data - Support for live data feeds and dynamic updates
  • Multiple Formats - CSV, JSON, GeoJSON, TopoJSON, KML, RSS, and more

Key Features

At the end of this documentation, you will be able to:

  • Set up an iXMaps environment to create interactive map visualizations
  • Load and process data from multiple sources efficiently
  • Create various types of data visualizations (choropleth, bubbles, symbols, charts)
  • Customize themes with styles, colors, and interactions
  • Implement advanced features like tooltips, legends, and data filtering
  • Integrate D3.js custom charts with map themes
  • Deploy interactive maps for web applications

Framework Components

iXMaps consists of five main components:

1. Data.js Library

Data processing engine supporting:

  • Multiple formats: CSV, JSON, GeoJSON, KML, RSS, JSONstat, TopoJSON
  • Data transformation: filtering, pivoting, aggregation, calculated columns
  • Multi-source loading with broker pattern
  • Real-time updates and live data feeds

Data.js does no reprojection — all input coordinates must be geographic WGS84 (EPSG:4326), i.e. decimal longitude/latitude. Convert any other CRS to EPSG:4326 before loading.

2. iXMaps Core

SVG-based interactive mapping framework:

  • Dynamic theme system for visualizations
  • Multi-layer support with geographic and data layers
  • Performance optimized for large datasets
  • Interactive features: zoom, pan, search, tooltips

3. Visualization grammar

A declarative, JSON-based layer definition system:

  • Each layer is described by data (source), binding (field→visual mapping), type (visualization method), and style (appearance)
  • iXMaps theme specifications are pure JSON objects — no imperative rendering code required
  • The same grammar drives choropleth maps, bubble charts, flow lines, sparklines, and custom D3 symbols

4. User API

The central JavaScript object ixmaps gives you the API to:

  • create and embed interactive maps
  • load themes or projects
  • change theme styles
  • get information about the actual visualization state

5. UI Components

Rich HTML interface elements:

  • Tooltip system with Mustache templating
  • Automatic legend generation
  • Search interface (normal and advanced)
  • Data visualization controls

Who Should Use iXMaps?

iXMaps is ideal for:

  • Data Scientists - Visualizing geographic data and patterns
  • Web Developers - Creating interactive map applications
  • Journalists - Building data-driven stories with maps
  • Researchers - Exploring and presenting spatial data
  • Government Agencies - Publishing open data visualizations

What is it NOT?

iXMaps is not:

  • A tile-based mapping library like Leaflet or Google Maps (though it can work with them)
  • A GIS system for spatial analysis
  • A backend server or database system
  • A static map generator (it’s designed for interactive visualizations)

Technology Stack

iXMaps is built on:

  • JavaScript (ES6+) - Core programming language

  • SVG - Vector graphics for maps and visualization

  • jQuery (optional) - DOM manipulation and utilities

  • Mustache - Template engine for tooltips and labels

  • Papaparse - CSV parser

  • Duckdb WASM - for reading parquet and geoparquet and geo package

  • flatgeobuf - read .fgb files, also partially

  • geobuf - read geo buffer files

License

iXMaps is licensed under BSD 3-Clause License, making it free for both personal and commercial use provided the original copyright notice is included and the original authors’ names may not be used to promote derived products

Credits

iXMaps was created and is maintained by Guenter Richter.

CDN

Include iXMaps in any HTML page with a single <script> tag — no installation, no build step:

<script src="https://cdn.jsdelivr.net/gh/gjrichter/ixmaps-flat@1/ixmaps.js"></script>

Community and Support

Ready to start? Head over to the Quick Start Guide to create your first map!