Native TypeScript interface to the GADM administrative boundaries database, engineered for web performance and instant geospatial queries.
Why We Built This
When building the PoolyPress GridSearch Playground and other advanced mapping tools for the PolyMech ecosystem, we needed to perform complex geospatial intersections—instantly fetching complex boundary polygons (like countries, states, and municipalities) and visualizing them on interactive maps. We also needed to enrich these regions with dense demographic data (like population and built-up concrete zones) on the fly.
Doing this mathematically at runtime for every user request is incredibly slow. Complex geometries require merging hundreds of polygons, which can freeze the browser and choke traditional APIs. We evaluated existing solutions, but they either relied on heavy Python backends (like the excellent pygadm library) or required setting up and maintaining expensive PostGIS/QGIS server clusters.
We needed a tool that was lightning-fast, had absolutely zero Python dependencies, and ran entirely inside Node.js. So, we ported the core Parquet-based methodology into the JavaScript ecosystem and supercharged it with web-first optimizations.
How It Works: The TypeScript Engine
@polymech/gadm transforms a massive geospatial database into instant front-end ready API delivery through a unique architecture:
1. Parquet-Powered Flat Database
At its core, the package loads 356,000 administrative rows from GADM 4.1, compressed into a single, extremely fast 6MB Parquet file. This replaces the need for an active SQL connection and allows us to hold the entire administrative hierarchy in memory. It supports lightning-fast fuzzy Levenshtein lookups across Level 0 (Country) all the way down to Level 5 (Municipality).
2. Aggressive Geometry Simplification & Cascading Caches
Raw boundary polygons can exceed 25MB—far too heavy for seamless React mapping. Our engine natively implements @turf/simplify to instantly compress these geometries down to ~1MB browser-friendly payloads.
Because dissolving and merging geometry still takes time, the engine relies on Cascading Caches. It automatically resolves cached geographic features across different environments (GADM_CACHE, process.cwd(), and local workspaces), guaranteeing sub-millisecond API delivery times without recalculating complex intersections.
3. Native GeoTIFF Data Enrichment
One of the most powerful features is the built-in demographic enrichment. The package natively reads the European Commission GHSL (Global Human Settlement Layer) GeoTIFFs directly in Node.js.
When requesting a boundary, it automatically scans the density per feature to calculate the exact simulated 2030 Population and the Built-up Concrete Metric Weight. By projecting bounding boxes to Mollweide EPSG:54009 and extracting spatial windows from the raw satellite TIFF data, we get perfect 100m² resolution density analytics on the fly—completely eliminating the need for an external GIS database. The data is even attached naturally to the GeoJSON feature.properties.
The C++ Batch Generator Pipeline
While the TypeScript engine is perfect for runtime delivery, pre-generating and dissolving the geometries for all 263 countries across 6 administrative levels (npm run boundaries -- --country=all) is mathematically intense.
For massive offline batch generation, we built a native C++ pipeline (gadm-boundaries).
- It uses industry-standard libraries like GDAL, GEOS, and PROJ.
- It performs geometry unions using full WKB-precision to avoid floating-point drift from traditional text roundtrips.
- It features windowed raster I/O for efficient TIFF parsing without blowing up machine RAM.
The C++ pipeline outputs identically structured, pre-enriched JSON artifacts that act as a direct drop-in replacement. The TypeScript wrapper automatically discovers these pre-generated caches and serves them instantly, unifying the offline heavy lifting with our lightning-fast Node.js delivery API.