DeanChensj / jiangshan-map
- вторник, 17 ноября 2026 г. в 00:00:05
江山时序 · 中国历史交互地图时间轴 (403 BCE – Present) | Interactive Historical Atlas of China across 18 dynasties, 198 territory snapshots, ancient-to-modern place genealogy & classical poetry routes
English · 简体中文 (Chinese) · 繁體中文 (Traditional Chinese) · 日本語 (Japanese)
An Interactive Historical Atlas of China from the Warring States (403 BCE) to the Present — Scrub Through Time, Trace Ancient Cities, and Walk in the Footsteps of History
Play Live Demo (English UI) → https://deanchen.me/jiangshan-map/?lang=en
The story behind it (in Chinese): From textbook maps to 1k GitHub stars
Have you ever wondered while reading Chinese history or classical poetry:
Chronicles of the Realm (jiangshan-map) brings together 2,400+ years of Chinese history across 18 historical periods into a single interactive parchment atlas—featuring multi-stage territorial and prefecture snapshots, ancient cities, strategic mountain passes, poetic and battlefield landmarks, chronological milestones, and reigning monarchs & imperial eras. No heavy print atlases required—just drag the timeline and click any city to travel through space and time.
100 BCE · Western Han · Emp. Wu, 630 CE · Tang · Emp. Taizong, 1700 CE · Qing · Kangxi Emp. (Shengzu)); the Chinese interface also shows the regnal era year (唐太宗·贞观四年).Yingtian Prefecture or Three Kingdoms Jingzhou) to inspect its jurisdiction and modern provincial equivalents. In the top-right Layers menu, Provinces (on by default) draws today's provincial boundaries over the historical map, and Prov. Names adds their names.Click any ancient city or mountain pass on the map (or double-click anywhere on the canvas) to open its Trace Place genealogy card:
Capital badges and dynastic seat remarks.Chronicles pill in the top-right of the card to filter for dynasties with major events, and click any event to time-travel straight to that year!Try It Live: High Tang Kaiyuan 29 (741 CE) · Open Chang'an's 2,400-Year Genealogy Card →
Click the top-left Universal Search Box (with a rotatable e.g. figure preview and quick-search chips, or type any monarch, general, statesman, monk, or poet such as Cao Cao, Huo Qubing, Sima Qian, Yue Fei, or Zheng He) to open Person Chronicle (点人溯事), marking every milestone of their life with numbered pins across changing dynastic borders:
Li Bai, Du Fu, Gao Shi or Cao Cao, Liu Bei, Sun Quan) to merge their journeys onto one timeline. Places where they met in the same year are marked as shared encounters, and the Shared N pill narrows the list to just those stops.Each time you step to the next event (‹ / ›, ← / →, or Space to auto-play), the timeline year, reigning monarch, imperial era, and dynastic territories evolve in sync with their footsteps, highlighting the active transition arc alongside bilingual primary-source excerpts and poems written at that exact site.
Try It Live: Su Dongpo's Life & Exile Across Song China (1037–1101 CE) →
Think you know Chinese historical geography? Click Quiz › in the corner of the Universal Search Box guide bar (or type quiz for Map Pinpoint · Ancient Place Quiz):
Confirm ↵ chip next to the pin to lock in your answer with concentric distance score rings, and earn points based on great-circle distance to the true coordinates!Try It Live: Western Han Emperor Wu, Yuanshou 2 (121 BCE) · Start the Map Pinpoint Challenge →
| Key / Action | Effect |
|---|---|
/ or Cmd/Ctrl + K |
Focus the Universal Search Box: search historical figures (Qin Shi Huang/Zhang Qian/Su Shi), ancient & modern cities (Xianyang/Chang'an/Luoyang/Kaifeng), reigning monarchs (Emperor Wu of Han/Taizong of Tang/Liu Che/Li Shimin), imperial eras (Zhenguan/Yongle/Kangxi), poetic & battlefield landmarks (Red Cliffs/Wuzhang Plains/Languan/Lanting), mountain passes (Hangu Pass/Jianmen Pass/Yumen Pass), historical events, or the Ancient Place Quiz |
← / → or bottom ‹ / › |
Jump to the previous / next historical phase, milestone event, or person event stop (hold Shift + ← / → to step by 10 years) |
Space |
Auto-play / pause timeline evolution (or auto-advance stops in Person Chronicle mode) |
Esc |
Close active popups/cards, clear search highlights, or exit custom multi-stop routes |
Single-click city / Double-click map |
Open the 18-era Trace Place & Key Events genealogy card for that location |
Hover / Click legend swatch |
Hover to isolate & highlight that polity's territory; click to open its profile and zoom to its territory |
Append query parameters to share any historical moment, battle, city genealogy, or multi-stop route:
?year=-403&lang=en (403 BCE · Partition of Jin) / ?year=-121&lang=en (121 BCE · Huo Qubing opens the Hexi Corridor) / ?year=648&lang=en (648 CE · Four Garrisons of Anxi & Wang Xuance in India) / ?year=1288&lang=en (1288 CE · Yuan Xuanzhengyuan over Tibet) / ?year=1881&lang=en (1881 CE · Zeng Jize recovers Ili) / ?year=1945&lang=en (1945 CE · Retrocession of Taiwan)?year=-260&place=长平&lang=en (Battle of Changping) / ?year=208&place=赤壁&lang=en (Battle of Red Cliffs) / ?year=383&place=淝水&lang=en (Battle of Fei River)?year=741&place=长安&lang=en (Chang'an / Xi'an) / ?year=1415&place=应天府&lang=en (Jiankang / Yingtian / Nanjing) / ?year=819&place=蓝关&lang=en (Han Yu at Languan Pass)?year=763&place=剑外,巴峡,巫峡,襄阳,洛阳&lang=en (Du Fu's 763 CE homeward route) / ?year=1079,1080,1094,1097&place=湖州,黄州,惠州,儋州&lang=en (Su Shi's multi-year exile route across Huzhou, Huangzhou, Huizhou, and Danzhou)?person=qinshihuang&lang=en (Qin Shi Huang) / ?person=zhangqian&lang=en (Zhang Qian) / ?person=zhugeliang&lang=en (Zhuge Liang) / ?person=xuanzang&lang=en (Xuanzang) / ?person=libai&lang=en (Li Bai) / ?person=sushi&lang=en (Su Shi) / ?person=wangyangming&lang=en (Wang Yangming)?person=libai,dufu&lang=en (Li Bai & Du Fu) / ?person=caocao,liubei,sunquan&lang=en (Cao Cao, Liu Bei & Sun Quan) / ?event=qintongyi&lang=en (Qin's Conquest of the Six States) / ?event=chuhan&lang=en (Chu–Han Contention) / ?event=anshi&lang=en (An Lushan Rebellion) / ?event=jingkang&lang=en (Jingkang Catastrophe)?year=-121&quiz=locate&lang=en (Map Pinpoint Challenge)?lang=en (English) / ?lang=zh-tw (Traditional Chinese) / / (Simplified Chinese)Put any view of the atlas into a blog post, Notion page, or course site:
&embed=1.<iframe>:<iframe
src="https://deanchen.me/jiangshan-map/?embed=1&year=1104&trace=101.778,36.617&from=1072&to=1126&lang=en"
width="100%" height="480" loading="lazy" style="border:0"
title="Chronicles of the Realm · 1104 CE, Northern Song"></iframe>The embedded map hides the site chrome and keeps only the map, a compact timeline, a title chip, an "Open in Jiangshan Atlas ↗" link, and a note that historical borders are approximate. Readers click once to start panning and zooming, so scrolling your page never gets stuck on the map.
| Parameter | Effect |
|---|---|
embed=1 |
Turn on embed mode (required) |
year, polity, person, stop, trace, lang |
Same as the share links above |
from=1072&to=1126 |
Limit the timeline to this range; the timeline zooms to show only it |
lock=1 |
Freeze the map at year and hide the timeline |
autoplay=1 |
Play a person's trajectory stop by stop (with person), or play the timeline |
WeChat Official Accounts, Zhihu, and Xiaohongshu do not allow iframes; share the plain link there instead.
Chronicles of the Realm works out of the box as a historical-geography visualization engine for LLMs, MCP Clients, and AI Agents. Models never need to guess latitude/longitude coordinates—simply extract two semantic parameters from a poem or historical text, year and place, and the atlas automatically resolves ancient/modern place names, centers the camera, renders dynastic borders and multi-stop trajectories, and opens the Trace Place genealogy card:
llms.txtstdio): scripts/mcp_server.js — add to Claude Desktop, Cursor, Windsurf, or Gemini CLI mcpServers:
{
"mcpServers": {
"jiangshan-atlas": {
"command": "node",
"args": ["/absolute/path/to/jiangshan-map/scripts/mcp_server.js"]
}
}
}<5ms offline response, zero npm dependencies):
inspect_place({ year, place, lang? }): Returns reigning monarch/era, controlling regime (polity), macro-region (dao/lu/province), prefecture (jun/zhou/fu), modern province/city, 2,400-year lore, and shareable deep-link URL.inspect_person({ person, stop?, lang? }): Returns a historical figure or monarch's biography, chronological geocoded stops across dynasties, and shareable deep-link URL.search_atlas({ query, limit?, lang? }): Searches across all ancient cities, poetic & battlefield landmarks, mountain passes, historical figures, imperial eras, and chronological milestones.skills/jiangshan-atlas/SKILL.md (includes the zero-dependency CLI renderer skills/jiangshan-atlas/scripts/jiangshan.py)
# Install into Claude Code / Gemini / Jetski global skills directory:
mkdir -p ~/.claude/skills ~/.gemini/config/skills && cp -r skills/jiangshan-atlas ~/.claude/skills/ && cp -r skills/jiangshan-atlas ~/.gemini/config/skills/| Mode | Example URL | Automatic Rendering Behavior |
|---|---|---|
| Single-Point Pinpoint (0D) | ?year=819&place=蓝关&lang=en(Han Yu's 819 CE exile poem at Languan Pass) |
Jumps to Tang Yuanhe 14 (819 CE), drops a pin on Languan Pass in the Qinling Mountains, and opens its 2,400-year administrative genealogy card |
| Same-Year Multi-Stop Route (1D) | ?year=763&place=剑外,巴峡,巫峡,襄阳,洛阳&lang=en(Du Fu's 763 CE poem on recapturing Henan & Hebei) |
Plots numbered vermilion arcs 1 → 5 across the 763 CE Tang map and auto-fits the viewport; click any stop to inspect its genealogy |
| Multi-Year Space-Time Route (4D) | ?year=1079,1080,1094,1097&place=湖州,黄州,惠州,儋州&lang=en(Su Shi's career across Huzhou, Huangzhou, Huizhou & Danzhou) |
Pairs year[i] with place[i], labeling stops with their historical years and switching the underlying dynastic map whenever you click a stop |
# Single-point poetic landmark screenshot
python3 skills/jiangshan-atlas/scripts/jiangshan.py --year 819 --place 蓝关 --out /tmp/languan_819.png
# Same-year multi-stop trajectory screenshot
python3 skills/jiangshan-atlas/scripts/jiangshan.py --year 763 --place 剑外,巴峡,巫峡,襄阳,洛阳 --out /tmp/dufu_763.png
# Multi-year space-time trajectory screenshot
python3 skills/jiangshan-atlas/scripts/jiangshan.py --year 1079,1080,1094,1097 --place 湖州,黄州,惠州,儋州 --out /tmp/sushi_exile.pngIn browser automation environments (Playwright) or WebMCP-enabled AI browsers (navigator.modelContext), the page automatically registers jiangshan_locate, jiangshan_inspect, and jiangshan_open_person, and exposes window.atlasAPI:
window.atlasAPI.locate({ year, place, zoom? }): Drives the map to a single location or multi-stop trajectory and returns structured historical-geographic metadata.window.atlasAPI.inspect({ year, place, person?, stop? }): Read-only query returning the controlling polity, ancient prefecture, modern province/city, leg distances, person events, and canonical shareable URL.window.atlasAPI.resolvePlace(place, year?): Resolves ancient and modern names for cities, strategic passes, poetic landmarks, and battlefields.window.atlasAPI.openPerson(person, stop?) & window.atlasAPI.search(query): Opens a person chronicle on the map or searches across the entire atlas.No dependencies or build steps required. Clone and serve with any static HTTP server:
git clone https://github.com/DeanChensj/jiangshan-map.git
cd jiangshan-map
python3 -m http.server 8000Then open http://localhost:8000 in your browser.
No local dependency needed. Build and start with Docker Compose:
docker compose up -d --buildThen open http://localhost:8008 (the port mapping 8008:80 is set in docker-compose.yml).
The image is a plain nginx:alpine that serves this repository as static files: Dockerfile copies the working tree into /usr/share/nginx/html, and .dockerignore keeps the build context small by excluding .git, .github, data/, docs/, scripts/, skills/, workers/, Markdown files, geojson/demo.html and the README demo images (assets/hero_demo_*.webp, assets/preview_*.webp) — the site does not need any of them at runtime.
To use another port, change the ports mapping in docker-compose.yml (e.g. "9000:80") and run docker compose up -d again.
After pulling upstream changes, rebuild with docker compose up -d --build. Without Compose: docker build -t jiangshan-map:latest . then docker run -d -p 8008:80 --name jiangshan-map jiangshan-map:latest.
Note: the image is built locally; it is not published to any registry.
The app ships its geometry as compact topology-deduplicated VLQ bundles. To use the vector layers in other projects, generate standard RFC 7946 GeoJSON (EPSG:4326, lon/lat) locally; the output goes to geojson/ and is not committed. The export covers 403 BCE to 1948; later years and the modern province layer are not included. The prefecture layer (郡 / 州 / 府) is left out by default because it derives from CHGIS, whose terms forbid redistribution; add --with-prefectures to include it for local academic, non-commercial use, and do not publish the result.
node scripts/export_geojson.js # or: node scripts/export_geojson.js <outDir>
node scripts/export_geojson.js --with-prefectures # adds the CHGIS-derived prefecture layer (local academic use only)snapshots/<id>.geojson — one file per territorial phase; each feature has a bbox and layer (polity / region, plus prefecture with --with-prefectures), title, title_en, category, tint, anchor.index.json — every dynasty's phases with from / to years (negative = BCE, no year 0) and the matching snapshot file.corridors.geojson (walls, canals, roads, sea routes), settlements.geojson, milestones.geojson, neighbors.geojson, and modern/ (rivers, lakes, hydro labels; appear / vanish give the years historical river courses and lakes are shown).To look up a point without loading every phase, use geojson/jiangshan-locate.js: it loads index.json plus only the snapshot covering the year, then runs a bbox-filtered point-in-polygon test.
const atlas = JiangshanLocate.create(); // or create({ base: '<url of geojson/>' })
const hit = await atlas.locate(118.78, 32.06, 1415); // lon, lat, year
hit.polity.properties.title; // 明
hit.region.properties.title; // 南直隶
hit.prefecture; // null unless exported with --with-prefectures (then 应天府)After exporting, serve the repository (python3 -m http.server 8000) and open http://localhost:8000/geojson/demo.html for a Leaflet example: drag the year slider, click the map, or open demo.html?year=1415&lon=118.78&lat=32.06 to load, highlight and zoom automatically. Historical borders are schematic approximations, not surveyed boundaries. The data is GPL-3.0 except the prefecture-level boundaries; see Data Sources & License.
Code and the data created by this project are released under GPL-3.0. One layer is not: the prefecture-level boundaries derived from CHGIS, which stay under CHGIS's own terms.
| Layer | Source | License |
|---|---|---|
| Code (app, scripts, CLI, MCP server) | This project | GPL-3.0 |
Polity outlines (polity) |
Started from aourednik/historical-basemaps (GPL-3.0), then redrawn by hand against historical texts | GPL-3.0 |
First-level divisions (region: 刺史部 / 道 / 路 / 省 …) |
Drawn by hand from historical texts; the source of early versions was not recorded | GPL-3.0 |
Prefecture-level boundaries (prefecture: 郡 / 州 / 府, incl. Warring States and Qin commanderies) |
Derived from CHGIS V6 and the Robert M. Hartwell China Historical GIS, simplified to 0.01° and edited by hand | Not GPL-3.0. Academic, non-commercial use only; do not redistribute. See below |
| Settlements, milestones, journeys, person chronicles, place lore | Compiled by this project from historical texts | GPL-3.0 |
| Modern provinces | DataV GeoAtlas (Alibaba Cloud) | Subject to DataV GeoAtlas terms |
| Rivers, lakes, neighbouring countries | Public-domain data | Public domain |
| Terrain hillshade | Rendered by scripts/build_terrain_tiles.py from AWS Terrain Tiles (public-domain SRTM, GMTED2010, ETOPO1); only shaded images at no finer than about 1 km per pixel are published |
GPL-3.0 (images) |
| Guqin audio | Wikimedia Commons (Liu Shui, Pingsha Luoyan, Yangguan Sandie, Zuiyu Changwan, Jiu Kuang) | Public domain |
Scholarly references (not data sources). Boundaries are checked against historical texts and Tan Qixiang's The Historical Atlas of China (谭其骧主编《中国历史地图集》). No map images or data from that atlas are included in this repository.
Prefecture-level boundaries (CHGIS). This layer is not covered by GPL-3.0 and is shown here for non-commercial, educational use. Do not republish it from this repository; if you need prefecture boundaries, download CHGIS from its official distribution (Harvard Dataverse) under its terms. scripts/export_geojson.js leaves this layer out unless run with --with-prefectures. Cite it as: CHGIS, Version: 6. © Fairbank Center for Chinese Studies of Harvard University and the Center for Historical Geographical Studies at Fudan University, 2016. Provenance details: data/atlas/README.md.
Approximate boundaries. Historical territories and administrative boundaries are schematic approximations of broad jurisdictions, not surveyed borders. Do not cite them as precise or authoritative.
Reusing this project. For the GPL-3.0 layers, credit 江山时序 Jiangshan Atlas with a link to https://github.com/DeanChensj/jiangshan-map and cite the upstream sources above. Screenshots that show the prefecture layer carry the CHGIS terms as well.
Rights holders. If you hold rights in any material here and believe it is used improperly, please open an issue; we will respond and remove it if needed.
Contributing: see CONTRIBUTING.md (中文贡献指南) for repository structure, data conventions, and validation checks.
Report a data error: found a wrong year, place or description? Open a data correction issue and cite a source if you can.
Copyright © 2026 DeanChensj. Licensed under GPL-3.0 (see LICENSE), except as noted above.