
Atlaspi
io.github.Soil911由 GitHub 帳號 Soil911 發布v0.10.2更新於 Oct 24, 2026
Historical geography for AI agents: polities, GeoJSON borders, chains & events, 4500 BCE-today
概覽
AtlasPI 為助理提供結構化的歷史地理資料:從公元前4500年至今的政權、GeoJSON 邊界、事件與學術來源。
- 可以做什麼
- 依名稱、類型、年份、狀態或洲別檢索歷史實體,並取得完整詳情記錄
- 取得指定年份的世界快照、依座標尋找附近實體,以及同時期或相關實體
- 比較二到四個實體,並追溯單一實體的時間演變、鏈條與事件
- 依世紀、類型、洲別或狀態彙總統計,並匯出為 GeoJSON、CSV 或時間軸資料
- 適用情境
- 適合回答關於歷史疆域、邊界、王朝或事件的問題,也適合建立需要結構化、可引用歷史地理資料而非純文字來源的地圖與時間軸。
- 執行需求
- 以本機 Python 套件(atlaspi-mcp)透過 stdio 執行;可用環境變數 ATLASPI_API_URL 指定其他 API 基礎位址,預設使用公開的 AtlasPI 服務。未說明需要 API 金鑰或註冊。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Atlaspi,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
🌍 AtlasPI
The structured historical geographic database built for AI agents.
Query any empire, kingdom, or territory from 4500 BCE to 2024 — with coordinates,
boundaries, confidence scores, and 2,000+ academic sources.
[Try it live] [Version] [Entities] [Events] [Periods] [Cities] [Routes] [Chains] [Sites] [Rulers] [Tests] [License] [API] [MCP] [DOI]
✅ Free · No API key · No registration · Apache 2.0 · CORS-enabled
curl https://atlaspi.it/v1/snapshot/year/1250
Live: atlaspi.it · API Docs · Map App · MCP Server
Why AtlasPI exists
AI agents working with historical geography today face a fragmented landscape: raw shapefiles in Natural Earth, unstructured text in Wikipedia, scattered coordinates in Wikidata, and academic datasets locked behind incompatible formats. None of these were designed for machine consumption.
AtlasPI bridges this gap. It provides a single, structured REST API where an AI agent can ask "What territories existed in the Balkans in 1400?" or "Show me the boundary changes of the Ottoman Empire" and get back clean JSON with GeoJSON boundaries, confidence scores, academic citations, and honest metadata about what is certain and what is disputed.
Historical data is never neutral. Borders were drawn through conquest, names were imposed through colonization, populations were erased through genocide. AtlasPI does not sanitize this complexity -- it structures it, documents it, and makes it queryable.
Screenshot
The web UI supports keyboard shortcuts, deep linking (/app?year=1000), continent filtering, time playback animation, dark/light mode, and full i18n (English/Italian). Try it live at atlaspi.it.
Quick Start
The API is now live at http://localhost:10100 and the interactive docs at http://localhost:10100/docs.
Docker
API Documentation
AtlasPI exposes 23 REST endpoints under /v1/. Full interactive documentation is available at /docs (Swagger UI) and /redoc when the server is running.
Core Endpoints
Examples
Search for empires active in 1500 CE:
Get full details for entity #12:
Find entities contemporary to the Roman Empire:
Export all entities as GeoJSON:
Find entities near Rome active in 100 CE:
Snapshot of the world in 1500 CE:
Compare two entities side by side:
Response Example
Dataset Overview
How this data is curated — disclosure and correction (2026-07-23)
Curation of non-boundary records (entities, events, cities, rulers, routes, sites) is AI-assisted: LLM research agents propose metadata and candidate citations, an adversarial verification step rejects citations that do not exist or do not support the claim, and the maintainer supervises the pipeline. Records are not systematically reviewed by professional historians. Until the human citation audit (protocol) is published, treat citations as machine-verified, not human-audited. Earlier versions of this documentation said the dataset was "hand-curated" — that wording was inaccurate and has been retired. Full details: METHODOLOGY §2.4 · ETHICS-028 (EN).
1,006 historical entities + 643 historical events spanning 6,500 years of human civilization, backed by 5,000+ academic sources and documenting 2,000+ territory changes. Plus 1,249 archaeological sites, 105 historical rulers, 29 historical languages, 104 dynasty chains, 41 trade routes, 252 historical cities, and 55 historical periods. Events include battles, treaties, epidemics, genocides, colonial violence, massacres, deportations and natural disasters — with ETHICS-007 (no euphemisms) and ETHICS-008 (known_silence flag for erased/suppressed records).
Coverage by Region
Entity Types
15 categories: empire | kingdom | republic | confederation | city-state | dynasty | colony | disputed_territory | sultanate | khanate | principality | duchy | caliphate | federation | city
Time Coverage
- Earliest entity: 4500 BCE (ancient Mesopotamian civilizations)
- Latest entity: 2024 (modern states and disputed territories)
- Negative years represent BCE dates (e.g.,
-753= 753 BCE)
📖 Citation
If you use AtlasPI in research, teaching, or derivative datasets, please cite the project using the Zenodo concept DOI below. The concept DOI always resolves to the latest release — individual versions get their own per-release DOIs on top.
BibTeX
Plain-text citation
AtlasPI Project (2026). AtlasPI: A structured historical geographic database for AI agents, version 6.14.0. Zenodo. https://doi.org/10.5281/zenodo.19581784
Ethical Framework
Historical data carries the weight of conquest, displacement, and erasure. AtlasPI is built on four principles that govern every data decision:
1. Truth Before Comfort
Historical records include conquest, genocide, forced deportation, and cultural erasure. These facts are represented with precision, never sanitized. If a territory was seized by force, the acquisition_method field says so. If a population was decimated, the data shows it with sources. If a geographic name was imposed by erasing the original, both names are present.
2. No Single Version of History
Contested borders show all known versions, with dates and sources. Place names include the original local form alongside names in other relevant languages. Academic disputes are made explicit, not resolved by fiat. The database does not arbitrate history -- it documents it.
3. Transparency of Uncertainty
Every record carries a confidence_score from 0.0 to 1.0. Every data point includes sources[] with primary source citations. Records scoring below 0.5 are marked as status: "uncertain" (enforced at the data layer — see ETHICS-013; the distinct status: "disputed" is reserved for contested territories, ETHICS-003). An uncertain datum honestly labeled is more valuable than a fabricated certainty.
4. No Geographic or Cultural Bias
Place names use the local-language form as the primary name. Sources include non-Western historiography where available. Colonial conquests are documented from the perspective of the colonized, not only the colonizers.
These principles are enforced through automated ethical tests, documented decisions in
docs/ethics/, and# ETHICS:comments throughout the codebase. See CLAUDE.md for the full governance framework.
Architecture
Tech Stack
Project Structure
Key Design Decisions
- Dual database support: SQLite for zero-config local development, PostgreSQL + PostGIS for production spatial queries.
- Auto-seeding: The database populates itself on first launch from JSON entity files -- no manual migration needed.
- GZip compression, CORS, rate limiting (60 req/min), and security headers enabled by default.
- Structured logging: JSON format in production, human-readable in development.
Testing
The test suite covers five dimensions:
Contributing
Contributions are welcome. Before you start:
- Read CLAUDE.md -- it contains the project's core values and development conventions.
- Check
docs/ethics/-- understand the ethical decisions already made. - Check
docs/adr/-- understand the architectural decisions already made.
Guidelines
- Code is written in English; documentation in Italian (except this README).
- Every function touching sensitive historical data must include an
# ETHICS:comment explaining the design choice. - Tests must cover ethical edge cases, not only technical ones.
- New entity data must include
sources[]with verifiable academic citations. - Disputed territories must have
confidence_score <= 0.7andstatus: "disputed".
Adding Historical Entities
Entity data lives in data/entities/ as JSON files. Each entity requires:
- Primary name in the original/local language
- At least one academic source
- A confidence score reflecting source reliability
- Territory changes with dated boundaries where available
Development Setup
Roadmap
See ROADMAP.md for the full development plan. Key upcoming milestones:
- PostgreSQL + PostGIS spatial queries in production
- Full GeoJSON boundary coverage for all entities
- Wikidata/OpenStreetMap ingestion pipelines
- Premium API tier with higher rate limits
- Hosted instance with public access
How to Cite
If you use AtlasPI in academic work, teaching, or derivative datasets, please cite it. A machine-readable CITATION.cff is provided in the repository root and is recognized by GitHub, Zenodo, Zotero, and most reference managers.
Suggested citation (software)
Ramadani, C. (2026). AtlasPI: A structured historical geographic database for AI agents (Version 6.1.2) [Software]. CRA. https://doi.org/10.5281/zenodo.19581784
BibTeX
Citing the underlying boundary sources
AtlasPI derives its geographic boundaries from two upstream datasets. If your work depends on spatial precision, please also cite them directly:
- Natural Earth (public domain) — post-1800 modern administrative boundaries. https://www.naturalearthdata.com/
- aourednik/historical-basemaps (CC BY 4.0) — pre-1800 historical world timestamps. Ourednik, A. historical-basemaps. https://github.com/aourednik/historical-basemaps
For full methodology on how boundaries are assigned, matched, and confidence-scored, see docs/METHODOLOGY.md.
The dataset has a permanent DOI minted by Zenodo: 10.5281/zenodo.19581784 (concept DOI, always resolves to the latest version). Every tagged release mints a new version DOI; see the Zenodo record for v6.1.2 specifically. Deposition metadata is in .zenodo.json.
License
AtlasPI follows an open core model.
The core project -- API, data models, ethical framework, and documentation -- is released under the Apache License 2.0.
Imported datasets retain their original licenses. Every source is tracked and attributed. Premium components (hosted services, curated datasets, enterprise features) are maintained separately from the open source core.
See LICENSE for the full Apache License 2.0 text and NOTICE for third-party attributions.
Acknowledgments
AtlasPI builds on the work of:
- Natural Earth -- public domain vector map data for modern boundaries
- aourednik/historical-basemaps -- historical world boundary data
- OpenStreetMap -- geographic data under ODbL
- Wikidata -- structured knowledge base under CC0
And the countless historians, cartographers, and researchers whose work makes structured historical geography possible.
Built with the conviction that historical truth, including its uncomfortable parts, should be structured, accessible, and machine-readable.
來源:README.md,提交 b5a6107
工具
0版本歷史
1- v0.10.2最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分