atlaspi

🌍 AtlasPI

为 AI Agent 打造的结构化历史地理数据库。

查询公元前 4500 年至 2024 年的任意帝国、王国或领土 — 获取坐标、
边界、置信度评分和 2,000 多条学术来源。

✅ 免费 · 无需 API 密钥 · 无需注册 · Apache 2.0 · 支持 CORS
curl https://atlaspi.it/v1/snapshot/year/1250

在线服务：atlaspi.it · API 文档 · 地图应用 · MCP 服务

---

AtlasPI 的存在意义

如今，处理历史地理信息的 AI Agent 面临着支离破碎的数据环境：Natural Earth 中的原始 shapefile、Wikipedia 上的非结构化文本、Wikidata 中零散的坐标，以及被锁在互不兼容格式中的学术数据集。这些数据都不是为机器处理而设计的。

AtlasPI 填补了这一空白。它提供统一的结构化 REST API，AI Agent 可以借此询问*“1400 年的巴尔干地区有哪些领土？”或“展示奥斯曼帝国的边界变化”*，并获得简洁的 JSON，其中包含 GeoJSON 边界、置信度评分、学术引文，以及如实说明哪些内容确定、哪些存在争议的元数据。

历史数据从来都不是中立的。边界因征服而划定，名称因殖民而强加，人口因种族灭绝而遭抹去。AtlasPI 不会粉饰这种复杂性——它将其结构化、记录下来，并使其可供查询。

截图

Web UI 支持键盘快捷键、深层链接（/app?year=1000）、大洲筛选、时间播放动画、深色／浅色模式，以及完整的国际化支持（英语／意大利语）。欢迎在线体验：atlaspi.it。

---

快速开始

# Clone the repository
git clone https://github.com/Soil911/AtlasPI.git
cd AtlasPI

# Install dependencies
pip install -r requirements.txt

# Run the server (auto-seeds the database on first launch)
python run.py

API 现已在 http://localhost:10100 上运行，交互式文档位于 **http://localhost:10100/docs**。

Docker

docker compose up --build

---

API 文档

AtlasPI 在 /v1/ 下提供 23 个 REST 端点。服务运行时，可在 /docs（Swagger UI）和 /redoc 查看完整的交互式文档。

核心端点

方法	端点	描述
GET	/v1/entity	使用筛选条件（名称、年份、状态、类型）查询实体
GET	/v1/entities	所有实体的分页列表
GET	/v1/entities/{id}	单个实体的完整详情
GET	/v1/search?q=	自动补全搜索
GET	/v1/types	列出可用的实体类型
GET	/v1/stats	数据集统计信息
GET	/v1/continents	可用的大洲／地区筛选条件
GET	/v1/random	随机实体（可选类型／年份／状态／大洲筛选条件）
GET	/v1/aggregation	按世纪、类型、大洲、状态汇总统计数据
GET	/v1/nearby?lat=&lon=	查找坐标附近的实体（含距离）
GET	/v1/snapshot/{year}	指定年份的世界状态（摘要 + 实体）
GET	/v1/compare/{id1}/{id2}	两个实体的结构化比较
GET	/v1/compare?ids=1,2,3	多实体比较（2-4 个），包含事件、关系链和重叠情况
GET	/v1/entities/{id}/contemporaries	时间段重叠的实体
GET	/v1/entities/{id}/related	按类型或地区查找相关实体
GET	/v1/entities/{id}/evolution	实体完整的时间顺序演变
GET	/v1/export/geojson	导出为 GeoJSON FeatureCollection
GET	/v1/export/csv	导出为 CSV
GET	/v1/export/timeline	导出时间线数据
GET	/health	服务健康检查
GET	/embed	可嵌入 iframe 的地图视图
GET	/compare	交互式实体比较页面

示例

搜索公元 1500 年活跃的帝国：

curl "http://localhost:10100/v1/entity?type=empire&year=1500"

获取实体 #12 的完整详情：

curl "http://localhost:10100/v1/entities/12"

查找与罗马帝国同时存在的实体：

curl "http://localhost:10100/v1/entities/1/contemporaries"

将所有实体导出为 GeoJSON：

curl "http://localhost:10100/v1/export/geojson" -o atlas.geojson

查找公元 100 年活跃且位于罗马附近的实体：

curl "http://localhost:10100/v1/nearby?lat=41.9&lon=12.5&year=100&radius=500"

公元 1500 年的世界快照：

curl "http://localhost:10100/v1/snapshot/1500" | jq '.summary'

并排比较两个实体：

curl "http://localhost:10100/v1/compare/1/5"

响应示例

{
  "id": 1,
  "name": "Imperium Romanum",
  "name_variants": [
    {"name": "Roman Empire", "language": "en"},
    {"name": "Imperio Romano", "language": "es"}
  ],
  "entity_type": "empire",
  "year_start": -753,
  "year_end": 476,
  "status": "confirmed",
  "confidence_score": 0.95,
  "capital": {"name": "Roma", "lat": 41.9028, "lon": 12.4964},
  "territory_changes": [...],
  "sources": [
    {"citation": "...", "source_type": "academic"}
  ]
}

---

数据集概览

数据如何整理——披露与更正（2026-07-23）

非边界记录（实体、事件、城市、统治者、路线、遗址）的整理采用 AI 辅助：大模型研究 Agent 提出元数据和候选引文，随后通过对抗性验证步骤，剔除不存在或无法支持相关论断的引文，维护者则负责监督整个流程。记录未经专业历史学家系统审查。在人工引文审计（规程）发布之前，请将引文视为经机器验证，而非经人工审计。本文档的早期版本曾称该数据集为“人工整理”，这一表述并不准确，现已弃用。详情见：METHODOLOGY §2.4 · ETHICS-028 (EN)。

涵盖 6,500 年人类文明的 1,006 个历史实体 + 643 个历史事件，由 5,000 多份学术来源支持，记录了 2,000 多次领土变更。此外还包括 1,249 个考古遗址、105 位历史统治者、29 种历史语言、104 条王朝世系、41 条贸易路线、252 座历史城市和 55 个历史时期。事件包括战役、条约、流行病、种族灭绝、殖民暴力、屠杀、驱逐和自然灾害——遵循 ETHICS-007（不使用委婉措辞）和 ETHICS-008（为被抹去或压制的记录设置 known_silence 标记）。

按地区划分的覆盖范围

地区	实体	示例
亚洲	195	蒙古帝国、秦／汉／唐／宋／明、德川幕府、莫卧儿帝国、高棉、三国
欧洲	104	罗马帝国、拜占庭、基辅罗斯、汉萨同盟、十字军诸国、普鲁士
美洲	85	塔万廷苏尤（印加）、阿兹特克、玛雅、豪德诺索尼、巴西帝国、泰诺
非洲	78	马里、桑海、刚果王国、大津巴布韦、阿克苏姆、祖鲁、布干达
中东	70	阿契美尼德帝国、奥斯曼帝国、阿拔斯哈里发国、正统哈里发国、耶路撒冷王国
大洋洲与太平洋地区	8	原住民族、毛利 iwi、汤加王国、夏威夷王国

实体类型

15 个类别：empire | kingdom | republic | confederation | city-state | dynasty | colony | disputed_territory | sultanate | khanate | principality | duchy | caliphate | federation | city

时间范围

• 最早的实体： 公元前 4500 年（古代美索不达米亚文明）
• 最新的实体： 2024 年（现代国家和争议领土）
• 负年份表示公元前年份（例如，-753 = 公元前 753 年）

---

📖 引用

如果您在研究、教学或衍生数据集中使用 AtlasPI，请使用下方的 Zenodo 概念 DOI 引用本项目。概念 DOI 始终指向最新发布版本——每个具体版本还会有各自的版本 DOI。

BibTeX

@software{atlaspi_2026,
  author       = {{AtlasPI Project}},
  title        = {AtlasPI: A structured historical geographic database for AI agents},
  version      = {6.13.0},
  year         = {2026},
  doi          = {10.5281/zenodo.19581784},
  url          = {https://doi.org/10.5281/zenodo.19581784}
}

纯文本引用

AtlasPI Project（2026）。AtlasPI：面向 AI Agent 的结构化历史地理数据库，版本 6.14.0。Zenodo。https://doi.org/10.5281/zenodo.19581784

---

伦理框架

历史数据承载着征服、流离失所和抹除的沉重影响。AtlasPI 建立在四项原则之上，它们指导每一项数据决策：

1. 真相优先于安慰

历史记录包括征服、种族灭绝、强迫驱逐和文化抹除。我们会准确呈现这些事实，绝不粉饰。如果某片领土是以武力夺取的，acquisition_method 字段会如实说明。如果某个人口遭到大规模屠杀，数据会附上来源予以呈现。如果某个地名是通过抹去原名而强加的，则两个名称都会保留。

2. 历史没有唯一版本

对于存在争议的边界，会展示所有已知版本及其日期和来源。地名会同时列出原始本地形式，以及其他相关语言中的名称。学术争议会明确呈现，而不会武断裁定。数据库不对历史作出裁决——只负责记录。

3. 不确定性透明化

每条记录都有一个介于 0.0 到 1.0 之间的 confidence_score。每个数据点都包含带有一手资料引文的 sources[]。得分低于 0.5 的记录会标记为 status: "uncertain"（在数据层强制执行——参见 ETHICS-013；不同的 status: "disputed" 专用于存在争议的领土，参见 ETHICS-003）。诚实标注的不确定数据，比捏造出来的确定性更有价值。

4. 不偏袒任何地理或文化

地名以当地语言形式作为主要名称。在可行的情况下，来源会纳入非西方史学。对殖民征服的记录会从被殖民者的视角出发，而不只采用殖民者的视角。

这些原则通过自动化伦理测试、docs/ethics/ 中记录的决策，以及整个代码库中的 # ETHICS: 注释来落实。完整的治理框架请参见 CLAUDE.md。

---

架构

技术栈

组件	技术
API	FastAPI (Python 3.11+)
数据库（开发）	SQLite
数据库（生产）	PostgreSQL + PostGIS
验证	Pydantic v2
速率限制	SlowAPI
前端	Vanilla JS + Leaflet.js
容器化	Docker（多阶段构建）
CI	GitHub Actions（lint + test + build）

项目结构

atlaspi/
  src/
    api/            # FastAPI routes, schemas, error handling
    db/             # SQLAlchemy models, database setup, seed data
    ingestion/      # Data import pipelines, boundary extraction
    validation/     # Confidence scoring engine
  static/           # Web UI (HTML, CSS, JS)
  data/
    entities/       # Source entity data (JSON)
    raw/            # Original unmodified source data
    processed/      # Normalized data
  tests/            # 260 tests: technical, ethical, security, performance, data quality
  docs/
    adr/            # Architecture Decision Records
    ethics/         # Documented ethical decisions (ETHICS-001, 002, 003...)

关键设计决策

• 双数据库支持： SQLite 用于零配置本地开发，PostgreSQL + PostGIS 用于生产环境中的空间查询。
• 自动填充： 首次启动时，数据库会从 JSON 实体文件自动填充——无需手动迁移。
• 默认启用 GZip 压缩、CORS、速率限制（60 req/min）和安全标头。
• 结构化日志： 生产环境采用 JSON 格式，开发环境采用易读格式。

---

测试

测试套件涵盖五个方面：

# Run all tests
pytest

# Run with verbose output
pytest -v

类别	验证内容
技术	API 响应、分页、输入验证、边缘情况
伦理	ETHICS-001/002/003 合规性、有争议领土的处理、置信度阈值
安全	CORS、安全标头、结构化错误响应、速率限制
性能	所有端点的响应时间均小于 500ms
数据质量	来源完整性、区域多样性、实体类型覆盖范围

---

贡献

欢迎贡献。在开始之前：

1. 阅读 CLAUDE.md——其中包含项目的核心价值观和开发约定。
2. 查看 docs/ethics/——了解已经作出的伦理决策。
3. 查看 docs/adr/——了解已经作出的架构决策。

指南

• 代码使用英语编写；文档使用意大利语编写（本 README 除外）。
• 每个涉及敏感历史数据的函数都必须包含 # ETHICS: 注释，说明设计选择。
• 测试必须涵盖伦理边缘情况，而不只是技术方面。
• 新增实体数据必须包含带有可验证学术引文的 sources[]。
• 有争议的领土必须满足 confidence_score <= 0.7 和 status: "disputed"。

添加历史实体

实体数据以 JSON 文件形式存放在 data/entities/ 中。每个实体都需要：

• 使用原始／当地语言的主要名称
• 至少一个学术来源
• 反映来源可靠性的置信度评分
• 在可用时提供带日期的边界变化记录

开发环境设置

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check src/ tests/

# Test
pytest -v

---

路线图

完整开发计划请参阅 ROADMAP.md。即将实现的主要里程碑：

• 在生产环境中支持 PostgreSQL + PostGIS 空间查询
• 为所有实体完整覆盖 GeoJSON 边界
• 建立 Wikidata/OpenStreetMap 数据导入管道
• 推出具有更高速率限制的高级 API 层级
• 提供可公开访问的托管实例

---

如何引用

如果你在学术研究、教学或衍生数据集中使用 AtlasPI，请引用它。仓库根目录提供了机器可读的 CITATION.cff，GitHub、Zenodo、Zotero 和大多数参考文献管理器均可识别。

建议引用格式（软件）

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

@software{ramadani_atlaspi_2026,
  author       = {Ramadani, Clirim},
  title        = {AtlasPI: A structured historical geographic database for AI agents},
  version      = {6.1.2},
  year         = {2026},
  publisher    = {CRA},
  doi          = {10.5281/zenodo.19581784},
  url          = {https://doi.org/10.5281/zenodo.19581784},
  note         = {Live instance: https://atlaspi.it. Concept DOI (all versions): 10.5281/zenodo.19581784. Version v6.1.2 DOI: 10.5281/zenodo.19581785.}
}

引用底层边界数据来源

AtlasPI 的地理边界来自两个上游数据集。如果你的工作依赖空间精度，请同时直接引用它们：

• Natural Earth（公有领域）——1800 年之后的现代行政边界。https://www.naturalearthdata.com/
• aourednik/historical-basemaps（CC BY 4.0）——1800 年之前的历史世界时间戳。Ourednik, A. historical-basemaps。https://github.com/aourednik/historical-basemaps

有关边界如何分配、匹配和评定置信度的完整方法说明，请参阅 docs/METHODOLOGY.md。

该数据集拥有由 Zenodo 铸造的永久 DOI：10.5281/zenodo.19581784（概念 DOI，始终指向最新版本）。每个带标签的发行版本都会铸造一个新的版本 DOI；v6.1.2 的具体记录请参阅 Zenodo 记录。存档元数据位于 .zenodo.json。

---

许可证

AtlasPI 采用开放核心模式。

核心项目——API、数据模型、伦理框架和文档——根据 Apache License 2.0 发布。

导入的数据集保留其原始许可证。每个来源都会被跟踪并注明出处。高级组件（托管服务、精选数据集、企业功能）与开源核心分开维护。

完整的 Apache License 2.0 文本请参阅 LICENSE，第三方归属信息请参阅 NOTICE。

---

致谢

AtlasPI 基于以下项目的成果构建：

• Natural Earth——用于现代边界的公有领域矢量地图数据
• aourednik/historical-basemaps——历史世界边界数据
• OpenStreetMap——根据 ODbL 授权的地理数据
• Wikidata——根据 CC0 授权的结构化知识库

此外，还要感谢无数历史学家、制图师和研究人员，他们的工作使结构化历史地理成为可能。

---

_{我们坚信，历史真相（包括其中令人不适的部分）应当是结构化、易于获取且机器可读的。}