Jiangshan Map: Explore 2,400 Years of Chinese History on an Interactive Timeline
An interactive timeline map of 2,400 years of Chinese territories, cities, and people, with ancient-modern boundary comparison instead of static maps.
GitHub DeanChensj/jiangshan-map Updated 2026-11-17 Branch main Stars 6.7K Forks 793
JavaScript CSS HTML Python Dockerfile Historical Atlas of China Timeline GeoJSON Browser Application

🧭 Decision Guide

Try it if you

  • You need to show Chinese territorial changes from 403 BCE to the present across 18 historical periods
    The README section “Why It's Fun to Explore” describes 2,400+ years, 18 historical periods, and timeline scrubbing
  • You need to compare the Warring States, Three Kingdoms, or Song-Liao-Western Xia polities on one canvas
    README Feature 1, “Multi-Polity Confrontations on a Single Canvas”
  • You need names, administrative changes, and events for ancient cities such as Chang'an or Xianyang
    README Feature 2, “Trace Place,” describes 2,400-year administrative genealogy and site-specific events
  • You need to present historical routes for Qin Shi Huang or Zhang Qian with Person Chronicle
    README Feature 3 lists Qin Shi Huang and Zhang Qian Chronicle examples

Skip it if you

  • You need general geographic data outside the Chinese historical scope from 403 BCE to the present
    The README defines it as an “Interactive Historical Atlas of China from the Warring States (403 BCE) to the Present”
  • Your distribution model cannot accept the GNU GPLv3 license
    Project metadata lists GNU General Public License v3.0
  • You must have local-run commands and explicit version requirements immediately
    The supplied material lists the Run Locally section title but not its commands, versions, or contents

Requirements

  • For Voice Narration, you need “a browser with speech synthesis.”
  • The interactive experience is presented as a browser Live Demo at https://deanchen.me/jiangshan-map/?lang=en.
  • The project stack includes JavaScript, CSS, HTML, Python, and Dockerfile, but the supplied material gives no local installation versions.

Watch out

  • Voice narration uses browser speech synthesis rather than a separate voice engine
    README Feature 1, “Voice Narration,” explicitly says it requires a browser with speech synthesis
  • To view modern province boundaries, check that Provinces is enabled in Layers
    README Feature 1 says Provinces is on by default and Prov. Names displays province names
  • Timeline zooming requires dragging both end handles; double-click restores the full overview
    README Feature 1, “Zoomable Timeline”

Not stated in the README

  • The supplied README material does not include the concrete commands, image name, or version requirements for Run Locally and Run with Docker.
  • The material does not identify the exact data sources, validation process, or accuracy of historical boundaries.
  • The material does not state browser compatibility, mobile behavior, or performance metrics under heavy zooming.
  • The material only lists section titles for AI Agent, MCP, GeoJSON Export, and window.atlasAPI, without usage details or API stability information.
  • The material does not describe external contribution policy, Issue response time, or future release plans.

💡 Deep Analysis

6
Yes I maintain a JavaScript education website and need to embed Chronicles of the Realm while fixing the year, map center, hover target, and language through a URL. Is this project suitable as a reusable component?
For: A frontend engineer maintaining a JavaScript education website who wants to embed the historical map and deep-link to a specific year and place

Yes: the README provides page embedding, shareable deep links, and a browser JavaScript API, which supports fixed views inside an educational website.

  • The project is primarily JavaScript and runs as a browser-based interactive map, so users do not need professional GIS software.
  • The README provides a reproducible URL example: ?year=1415&zoom=1.75&center=115.8,33.2&hover=Yingtian%20Prefecture&lang=en, fixing the year, zoom, center, hover target, and language.
  • “Embed in Your Page” and window.atlasAPI show that the project is designed for embedding and programmatic control rather than only standalone browsing.
  • The interface supports Simplified Chinese, Traditional Chinese, English, and Japanese, which fits multilingual course pages.

However, the supplied README excerpt does not describe the embed code, API method signatures, cross-origin policy, mobile behavior, or version-compatibility guarantees. Those details must be checked in the full documentation before production integration.

  • Project data: main_language is JavaScript
  • README: "Embed in Your Page" and "Browser JavaScript API (`window.atlasAPI`)"
  • README Feature 1: `?year=1415&zoom=1.75&center=115.8,33.2&hover=Yingtian%20Prefecture&lang=en`
  • README header: English, Simplified Chinese, Traditional Chinese, and Japanese
Not stated in the README:The provided text does not show the embedding method, API methods, return values, or event model;It does not state whether a stable npm package, iframe contract, or production version-locking mechanism is provided
Yes In a secondary or university Chinese-history course, I need a browser demonstration of political changes from the Warring States in 403 BCE to the present, including ancient-city genealogies and person routes. Is this project suitable for classroom use?
For: A history teacher creating Chinese, English, or Japanese interactive demonstrations for secondary or university courses on browser-based classroom devices

Yes: it places the timeline, polities, ancient-place genealogies, and historical figures in one browser interface, matching classroom needs for explaining history across time and space.

  • The README covers more than 2,400 years from 403 BCE to the present across 18 historical periods, allowing teachers to scrub through major changes.
  • Multi-polity views include the Seven Warring States, the Three Kingdoms, the Northern and Southern Dynasties, the Five Dynasties and Ten Kingdoms, and the Song–Liao–Western Xia–Jin period, which supports demonstrations of concurrent states.
  • Trace Place shows names, administrative affiliations, capital status, and events across eras; Person Chronicles connect biographical milestones to the map.
  • The interface supports Simplified Chinese, Traditional Chinese, English, and Japanese, and browser Speech Synthesis provides narration for multilingual or auditory demonstrations.

The interface has many layers, routes, and timeline controls; touch behavior and speech quality depend on the browser. The README also states that historical boundaries are reconstructed or generalized and should not be treated as the sole scholarly interpretation.

  • README: "from the Warring States (403 BCE) to the Present," "18 historical periods," and "2,400+ years"
  • README Feature 1: "Multi-Polity Confrontations on a Single Canvas"
  • README Feature 2: "Trace Place" and "2,400-Year Administrative Genealogy"
  • README: "Voice Narration," requiring a browser with speech synthesis
  • Project insight, user_experience: basic exploration starts with the timeline, map objects, or search
Not stated in the README:Offline classroom use, asset size, and behavior under weak network conditions are not specified;The complete language coverage of narration, autoplay restrictions, and accessibility-standard support are not specified
Yes I am creating a classical-poetry feature about Su Shi, Han Yu, and Yue Fei and need to connect Huangzhou, Languan Pass, and Zhuxianzhen with events, person routes, and specific years. Can this project reduce the manual work of assembling maps and timelines?
For: A Chinese content creator using a desktop browser who needs to anchor places, events, and routes in article links about classical poetry and historical figures

Yes: the project already combines ancient-place genealogies, event jumps, person chronicles, and poetic landmarks in one time–space interface, reducing the manual work of assembling maps and timelines.

  • The README explicitly names Jiankang, Huangzhou, Languan Pass, and Zhuxianzhen as exploration examples connected with poetry and historical events.
  • Trace Place presents names, administrative affiliations, capital status, and site-specific events across 18 historical periods; clicking an event jumps to its year.
  • Feature 3, Person Chronicles, maps biographical milestones, battles, missions, or migrations onto the changing historical map, which fits person-centered articles.
  • Shareable Deep Links and Embed in Your Page can place a fixed year, center, location, and language into an article or embedded view.

However, person routes, poetic landmarks, and event associations are narratively curated and should not automatically be treated as the only scholarly interpretation. The excerpt does not say whether each item has a citable source note, exportable citation, or stable event ID.

  • README Why It's Fun to Explore: Jiankang, Huangzhou, Languan Pass, and Zhuxianzhen
  • README Feature 2: "Trace Place" and "Site-Specific Landmark Events," with event clicks that time-travel to the relevant year
  • Project insight, solution_analysis: Person Chronicle maps life events, battles, missions, or migrations
  • README omitted-section list: "Shareable Deep Links" and "Embed in Your Page"
Not stated in the README:It is not specified whether each place, person, and event has a stable ID, citation format, or source footnote;It is not specified whether deep links can simultaneously fix a person route, event filter, and layer state
It depends I maintain an open-source digital-humanities site and need to deploy Chronicles of the Realm with Docker while allowing the team to modify its JavaScript, CSS, and HTML. Is this project a suitable foundation under GPLv3 and data-licensing constraints?
For: An open-source maintainer who needs to deploy an accessible Chinese historical map site with Docker while complying with GPLv3 and third-party data licenses

It depends: the project provides a Docker deployment path and uses GPLv3, but the code license does not automatically cover historical data, text, images, or third-party resources.

  • The project is primarily JavaScript, CSS, and HTML, making it accessible to a frontend team; the repository also contains some Python and a Dockerfile.
  • The README includes “Run with Docker,” showing that deployment as a standalone web service is a supported path.
  • The project license is GNU GPLv3. Code reuse and modification are possible under its conditions, but redistribution must comply with GPLv3 source and licensing obligations.
  • The project insight explicitly warns that data, text, images, historical materials, and third-party resources may have separate terms; commercial deployment or redistribution requires more than checking the repository license.

It is therefore suitable as a code foundation, not proof that every map layer can be repackaged or used commercially. The supplied README excerpt does not list each dataset’s separate license, production Docker configuration, or external-resource inventory.

  • Project data: license is GNU General Public License v3.0
  • README omitted-section list: "Run with Docker"
  • Project data: language distribution includes JavaScript, CSS, HTML, Python, and Dockerfile
  • Project insight, usage_limitations: data, text, images, historical materials, and third-party resources may have separate licensing terms
Not stated in the README:Docker build parameters, ports, persistence requirements, and production deployment settings are not provided;The specific licenses and attributions for datasets, images, text, and third-party map resources are not listed;Additional requirements for modified distributions, branding, or external-service dependencies are not specified
It depends I am researching Chinese historical geography with QGIS or Leaflet and need data spanning 403 BCE to the present, 18 historical periods, and 198 territory snapshots. Can this project serve as a reusable historical geospatial data source?
For: A digital-humanities researcher using QGIS or Leaflet who needs to compare ancient administrative divisions with modern provincial boundaries

It depends: the project is suitable as a reusable visualization dataset, but not as a precise surveying source or a complete historical GIS database.

  • It separates territories, ancient administrative divisions, modern provincial borders, rivers, lakes, the Great Wall, canals, and routes, making it suitable for Leaflet, MapLibre, or QGIS workflows.
  • Coverage includes 18 historical periods and 198 territory snapshots. The Ghost Boundary Diff also represents gains and losses between adjacent phases.
  • The README explicitly describes ancient territories, coastlines, and administrative divisions as reconstructed or generalized results, not authoritative modern-style boundaries.
  • Research conclusions still require checking the listed sources and original historical materials, especially for disputed territories, routes, and event associations.

The README does not specify the complete GeoJSON schema, coordinate reference system, versioning policy, or precision level for each layer, so direct suitability for quantitative research remains uncertain.

  • Project insight, solution_analysis: GeoJSON export for Leaflet / MapLibre / QGIS
  • README Feature 1: "18 historical periods" and "198 territory snapshots"
  • README Feature 1: "Ghost Boundary Diff"
  • Project insight, usage_limitations: ancient territories, administrative divisions, and coastlines are reconstructed or generalized
Not stated in the README:The provided README text does not specify the GeoJSON fields, coordinate reference system, geometric precision, or file organization;It does not state whether each historical layer has independent sources, version numbers, or uncertainty metadata
It depends I am building a JavaScript AI tool that needs to query ancient-place genealogies, locate map states by year, and handle single-year or multi-year routes. Can this project's MCP, CLI, and browser API serve as integration entry points?
For: A JavaScript engineer building an AI tool or MCP client that needs model queries for historical years, places, and routes

It depends: the README explicitly provides MCP/LLM, CLI, and browser-API entry points, but the full tool protocol and data contracts are not included in the supplied excerpt.

  • “AI Agent, MCP & LLM Integration” and navigator.modelContext show that the project considers model-context interfaces for AI tools.
  • “CLI One-Command Screenshot & JSON Lookup” supports screenshots and JSON queries, which can help an agent locate map states, read structured results, or produce visual evidence.
  • The README lists the 0D Pinpoint, 1D Same-Year Route, and 4D Multi-Year Route URL Protocols, indicating support for places, same-year routes, and multi-year routes.
  • window.atlasAPI provides another integration path for AI functionality already running in a browser.

Whether it can be integrated directly into production AI orchestration depends on the actual MCP tool names, parameter schemas, JSON fields, error handling, authentication, and screenshot-command definitions. The project has four releases, but that alone does not establish long-term API stability.

  • README omitted-section list: "AI Agent, MCP & LLM Integration"
  • README omitted-section list: "CLI One-Command Screenshot & JSON Lookup (for Agent Tool Calls)"
  • README omitted-section list: "Browser JavaScript API (`window.atlasAPI`) & In-Browser WebMCP (`navigator.modelContext`)"
  • README omitted-section list: "0D Pinpoint / 1D Same-Year Route / 4D Multi-Year Route"
  • Project data: latest_release is v1.3.0 and release_count is 4
Not stated in the README:The MCP tool list, parameter schemas, JSON return structures, and error codes are not provided;The actual CLI commands, runtime dependencies, authentication, and stability commitments are not specified;It is not stated whether remote MCP services are supported or only local browser context

✨ Highlights

  • Covers 403 BCE to the present across 18 periods and 198 territory snapshots
  • Ghost Boundary Diff makes territorial gains and losses visually explicit
  • Trace Place connects 2,400 years of ancient city names and administrative changes
  • Supports multi-polity views, modern province overlays, and dynamic river courses
  • Person Chronicle maps the movements and milestones of figures such as Cao Cao and Zhang Qian

🔧 Engineering

  • Drag the timeline to switch between territories from Qin, Tang, Yuan, Qing, and other periods
  • Click an ancient city to open its Trace Place genealogy and event card
  • The Layers menu overlays Provinces and Prov. Names on historical maps
  • Browser speech synthesis can narrate years and historical events
  • Person Chronicle traces routes of figures such as Qin Shi Huang and Zhang Qian

⚠️ Risks

  • Voice Narration requires a browser with speech synthesis support
  • The README does not provide the concrete commands or versions for Run Locally
  • The project has only 10 contributors and 4 releases
  • The GPLv3 license may not fit projects requiring non-GPL distribution terms

👥 For who?

  • Developers researching Chinese historical territories and administrative changes
  • Frontend teams building interactive views of ancient cities, passes, and poetic routes
  • Users who want to explore historical maps through a JavaScript browser application