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 or and get back clean JSON with GeoJSON boundaries, confidence scores, academic citations, and honest metadata about what is certain and what is disputed.
Historical geography for AI agents: polities, GeoJSON borders, chains & events, 4500 BCE-today
ATLASPI_API_URL
Last checked
2026-11-09
Stars
—
Tools
—
Uptime
—
"What territories existed in the Balkans in 1400?"
"Show me the boundary changes of the Ottoman Empire"
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
# 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
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
Region
Entities
Examples
Asia
195
Mongol Empire, Qin/Han/Tang/Song/Ming, Tokugawa, Mughal, Khmer, Three Kingdoms
Europe
104
Roman Empire, Byzantine, Kyivan Rus', Hanseatic League, Crusader states, Prussia
Americas
85
Tawantinsuyu (Inca), Aztec, Maya, Haudenosaunee, Empire of Brazil, Taino
Africa
78
Mali, Songhai, Kingdom of Kongo, Great Zimbabwe, Aksum, Zulu, Buganda
Middle East
70
Achaemenid, Ottoman, Abbasid Caliphate, Rashidun, Kingdom of Jerusalem
Oceania & Pacific
8
Aboriginal nations, Maori iwi, Kingdom of Tonga, Hawaiian Kingdom
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
@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}
}
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
Component
Technology
API
FastAPI (Python 3.11+)
Database (dev)
SQLite
Database (prod)
PostgreSQL + PostGIS
Validation
Pydantic v2
Rate Limiting
SlowAPI
Frontend
Vanilla JS + Leaflet.js
Containerization
Docker (multi-stage build)
CI
GitHub Actions (lint + test + build)
Project Structure
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...)
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:
# Run all tests
pytest
# Run with verbose output
pytest -v
Category
What it verifies
Technical
API responses, pagination, input validation, edge cases
Source completeness, regional diversity, entity type coverage
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.7 and status: "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
# Install with dev dependencies
pip install -e ".[dev]"
# Lint
ruff check src/ tests/
# Test
pytest -v
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
@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.}
}
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:
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
