atlaspi

🌍 AtlasPI

AI エージェント向けに構築された、構造化された歴史地理データベースです。

紀元前4500年から2024年までの帝国、王国、領土を自由に検索できます。座標、
境界、確信度スコア、2,000件以上の学術資料も利用できます。

✅ 無料 · API キー不要 · 登録不要 · Apache 2.0 · CORS 対応
curl https://atlaspi.it/v1/snapshot/year/1250

公開中：atlaspi.it · API ドキュメント · 地図アプリ · MCP サーバー

---

AtlasPI の目的

現在、歴史地理を扱う AI エージェントは、断片化した情報環境に直面しています。Natural Earth の生のシェープファイル、Wikipedia の非構造化テキスト、Wikidata に散在する座標、互換性のない形式に閉じ込められた学術データセットなどがあります。いずれも、機械での利用を想定して設計されたものではありません。

AtlasPI はこのギャップを埋めます。単一の構造化された REST API を提供し、AI エージェントは「1400年のバルカン半島にはどのような領土が存在しましたか？」や「オスマン帝国の境界の変遷を見せてください」といった質問を行い、GeoJSON 境界、確信度スコア、学術文献の引用、そして確実な点と議論のある点を誠実に示すメタデータを含む、整った JSON を取得できます。

歴史データが中立であることはありません。国境は征服によって引かれ、名称は植民地化によって押し付けられ、住民はジェノサイドによって抹消されてきました。AtlasPI はこうした複雑さを覆い隠すのではなく、構造化し、記録し、検索可能にします。

---

スクリーンショット

ウェブ UI は、キーボードショートカット、ディープリンク（/app?year=1000）、大陸フィルター、時間再生アニメーション、ダーク／ライトモード、完全な i18n（英語／イタリア語）に対応しています。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}	2つのエンティティの構造化比較
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 CE に存在した帝国を検索：

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 CE に存在したローマ付近のエンティティを検索：

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

1500 CE の世界のスナップショット：

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

2つのエンティティを並べて比較：

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 の支援を受けて行われています。LLM リサーチエージェントがメタデータと引用候補を提案し、敵対的検証の手順で、実在しない引用や主張を裏付けない引用を却下し、メンテナーがパイプラインを監督します。レコードは専門の歴史家による体系的なレビューを受けていません。人による引用監査（プロトコル）が公開されるまでは、引用は機械検証済みであり、人による監査は未実施として扱ってください。このドキュメントの以前のバージョンでは、データセットを「手作業でキュレーション」と記載していましたが、この表現は不正確だったため廃止しました。詳細：METHODOLOGY §2.4 · ETHICS-028 (EN)。

歴史的エンティティ1,006件と歴史的イベント643件を収録し、人類文明の6,500年にわたる歴史を網羅しています。学術資料5,000件以上を根拠とし、領土の変遷2,000件以上を記録しています。さらに、遺跡1,249件、歴史上の支配者105人、歴史的言語29種、王朝の系譜104件、交易路41件、歴史的都市252件、歴史的時代55件を収録しています。イベントには、戦闘、条約、疫病、ジェノサイド、植民地支配下の暴力、虐殺、強制移送、自然災害が含まれます。ETHICS-007（婉曲表現を使用しない）およびETHICS-008（消去・抑圧された記録を示すknown_silenceフラグ）に準拠しています。

地域別の収録状況

地域	エンティティ数	例
アジア	195	モンゴル帝国、秦／漢／唐／宋／明、徳川、ムガル、クメール、三国
ヨーロッパ	104	ローマ帝国、ビザンツ帝国、キーウ・ルーシ、ハンザ同盟、十字軍国家、プロイセン
南北アメリカ	85	タワンティンスウユ（インカ）、アステカ、マヤ、ハウデノサウニー、ブラジル帝国、タイノ
アフリカ	78	マリ、ソンガイ、コンゴ王国、グレート・ジンバブエ、アクスム、ズールー、ブガンダ
中東	70	アケメネス朝、オスマン帝国、アッバース朝、正統カリフ時代、エルサレム王国
オセアニアと太平洋	8	アボリジナル諸民族、マオリのイウィ、トンガ王国、ハワイ王国

エンティティの種類

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 エージェント向けの構造化された歴史地理データベース, version 6.14.0. Zenodo. https://doi.org/10.5281/zenodo.19581784

---

倫理的枠組み

歴史データには、征服、強制移住、消去の重みが伴います。AtlasPIは、あらゆるデータ上の判断を導く4つの原則に基づいて構築されています。

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 形式、開発環境では人間が読みやすい形式を使用します。

---

テスト

テストスイートは、次の 5 つの側面を対象としています。

# 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" を設定する必要があります。

歴史上のエンティティの追加

エンティティデータは data/entities/ に JSON ファイルとして保存されています。各エンティティには、次の情報が必要です。

• 元の言語または現地語での主名称
• 少なくとも 1 件の学術的な出典
• 出典の信頼性を反映した信頼度スコア
• 入手可能な場合は、日付入りの境界を含む領土の変遷

開発環境のセットアップ

# 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は、2つの上流データセットから地理的境界データを取得しています。空間精度が重要となる研究では、これらのデータセットも直接引用してください。

• 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に基づく構造化ナレッジベース

また、構造化された歴史地理学を可能にする、数え切れないほど多くの歴史家、地図製作者、研究者の皆様に感謝します。

---

_{居心地の悪い側面も含めた歴史的事実は、構造化され、アクセス可能で、機械可読であるべきだという信念のもとに構築されています。}