{ "markdown": "

\n

๐ŸŒ AtlasPI

\n

\n The structured historical geographic database built for AI agents.\n

\n

\n Query any empire, kingdom, or territory from 4500 BCE to 2024 — with coordinates,
\n boundaries, confidence scores, and 2,000+ academic sources.\n

\n

\n\n

\n \"Try\n \"Version\"\n \"Entities\"\n \"Events\"\n \"Periods\"\n \"Cities\"\n \"Routes\"\n \"Chains\"\n \"Sites\"\n \"Rulers\"\n \"Tests\"\n \"License\"\n \"API\"\n \"MCP\"\n \"DOI\"\n

\n\n

\n โœ… Free ยท No API key ยท No registration ยท Apache 2.0 ยท CORS-enabled
\n curl https://atlaspi.it/v1/snapshot/year/1250\n

\n\n

\n Live: atlaspi.it ·\n API Docs ·\n Map App ·\n MCP Server\n

\n\n---\n\n## Why AtlasPI exists\n\nAI 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.\n\nAtlasPI 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.\n\nHistorical 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.\n\n---\n\n## Screenshot\n\n![AtlasPI Web UI โ€” the world in 1000 CE, 146 historical entities rendered from primary-source boundaries](docs/screenshot.png)\n\nThe 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](https://atlaspi.it/app)**.\n\n---\n\n## Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/Soil911/AtlasPI.git\ncd AtlasPI\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run the server (auto-seeds the database on first launch)\npython run.py\n```\n\nThe API is now live at **http://localhost:10100** and the interactive docs at **http://localhost:10100/docs**.\n\n### Docker\n\n```bash\ndocker compose up --build\n```\n\n---\n\n## API Documentation\n\nAtlasPI exposes 23 REST endpoints under `/v1/`. Full interactive documentation is available at `/docs` (Swagger UI) and `/redoc` when the server is running.\n\n### Core Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/v1/entity` | Query entities with filters (name, year, status, type) |\n| `GET` | `/v1/entities` | Paginated list of all entities |\n| `GET` | `/v1/entities/{id}` | Full detail for a single entity |\n| `GET` | `/v1/search?q=` | Autocomplete search |\n| `GET` | `/v1/types` | List available entity types |\n| `GET` | `/v1/stats` | Dataset statistics |\n| `GET` | `/v1/continents` | Available continent/region filters |\n| `GET` | `/v1/random` | Random entity (with optional type/year/status/continent filters) |\n| `GET` | `/v1/aggregation` | Aggregate stats by century, type, continent, status |\n| `GET` | `/v1/nearby?lat=&lon=` | Find entities near coordinates (with distance) |\n| `GET` | `/v1/snapshot/{year}` | World state at a given year (summary + entities) |\n| `GET` | `/v1/compare/{id1}/{id2}` | Structured comparison of two entities |\n| `GET` | `/v1/compare?ids=1,2,3` | Multi-entity comparison (2-4) with events, chains, overlap |\n| `GET` | `/v1/entities/{id}/contemporaries` | Entities with overlapping time periods |\n| `GET` | `/v1/entities/{id}/related` | Related entities by type or region |\n| `GET` | `/v1/entities/{id}/evolution` | Full chronological evolution of an entity |\n| `GET` | `/v1/export/geojson` | Export as GeoJSON FeatureCollection |\n| `GET` | `/v1/export/csv` | Export as CSV |\n| `GET` | `/v1/export/timeline` | Export timeline data |\n| `GET` | `/health` | Service health check |\n| `GET` | `/embed` | Embeddable map view for iframes |\n| `GET` | `/compare` | Interactive entity comparison page |\n\n### Examples\n\n**Search for empires active in 1500 CE:**\n```bash\ncurl \"http://localhost:10100/v1/entity?type=empire&year=1500\"\n```\n\n**Get full details for entity #12:**\n```bash\ncurl \"http://localhost:10100/v1/entities/12\"\n```\n\n**Find entities contemporary to the Roman Empire:**\n```bash\ncurl \"http://localhost:10100/v1/entities/1/contemporaries\"\n```\n\n**Export all entities as GeoJSON:**\n```bash\ncurl \"http://localhost:10100/v1/export/geojson\" -o atlas.geojson\n```\n\n**Find entities near Rome active in 100 CE:**\n```bash\ncurl \"http://localhost:10100/v1/nearby?lat=41.9&lon=12.5&year=100&radius=500\"\n```\n\n**Snapshot of the world in 1500 CE:**\n```bash\ncurl \"http://localhost:10100/v1/snapshot/1500\" | jq '.summary'\n```\n\n**Compare two entities side by side:**\n```bash\ncurl \"http://localhost:10100/v1/compare/1/5\"\n```\n\n### Response Example\n\n```json\n{\n \"id\": 1,\n \"name\": \"Imperium Romanum\",\n \"name_variants\": [\n {\"name\": \"Roman Empire\", \"language\": \"en\"},\n {\"name\": \"Imperio Romano\", \"language\": \"es\"}\n ],\n \"entity_type\": \"empire\",\n \"year_start\": -753,\n \"year_end\": 476,\n \"status\": \"confirmed\",\n \"confidence_score\": 0.95,\n \"capital\": {\"name\": \"Roma\", \"lat\": 41.9028, \"lon\": 12.4964},\n \"territory_changes\": [...],\n \"sources\": [\n {\"citation\": \"...\", \"source_type\": \"academic\"}\n ]\n}\n```\n\n---\n\n## Dataset Overview\n\n> **How this data is curated โ€” disclosure and correction (2026-07-23)**\n>\n> 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](docs/academic-audit/CITATION-AUDIT.md)) 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](docs/METHODOLOGY.md#24-events-cities-trade-routes-rulers-sites-periods-languages) ยท [ETHICS-028 (EN)](docs/ethics/ETHICS-028-ai-assisted-curation-transparency.en.md).\n\n**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).\n\n### Coverage by Region\n\n| Region | Entities | Examples |\n|--------|----------|---------|\n| Asia | 195 | Mongol Empire, Qin/Han/Tang/Song/Ming, Tokugawa, Mughal, Khmer, Three Kingdoms |\n| Europe | 104 | Roman Empire, Byzantine, Kyivan Rus', Hanseatic League, Crusader states, Prussia |\n| Americas | 85 | Tawantinsuyu (Inca), Aztec, Maya, Haudenosaunee, Empire of Brazil, Taino |\n| Africa | 78 | Mali, Songhai, Kingdom of Kongo, Great Zimbabwe, Aksum, Zulu, Buganda |\n| Middle East | 70 | Achaemenid, Ottoman, Abbasid Caliphate, Rashidun, Kingdom of Jerusalem |\n| Oceania & Pacific | 8 | Aboriginal nations, Maori iwi, Kingdom of Tonga, Hawaiian Kingdom |\n\n### Entity Types\n\n15 categories: `empire` | `kingdom` | `republic` | `confederation` | `city-state` | `dynasty` | `colony` | `disputed_territory` | `sultanate` | `khanate` | `principality` | `duchy` | `caliphate` | `federation` | `city`\n\n### Time Coverage\n\n- **Earliest entity:** 4500 BCE (ancient Mesopotamian civilizations)\n- **Latest entity:** 2024 (modern states and disputed territories)\n- Negative years represent BCE dates (e.g., `-753` = 753 BCE)\n\n---\n\n## ๐Ÿ“– Citation\n\nIf 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.\n\n### BibTeX\n\n```bibtex\n@software{atlaspi_2026,\n author = {{AtlasPI Project}},\n title = {AtlasPI: A structured historical geographic database for AI agents},\n version = {6.13.0},\n year = {2026},\n doi = {10.5281/zenodo.19581784},\n url = {https://doi.org/10.5281/zenodo.19581784}\n}\n```\n\n### Plain-text citation\n\nAtlasPI Project (2026). *AtlasPI: A structured historical geographic database for AI agents*, version 6.14.0. Zenodo. https://doi.org/10.5281/zenodo.19581784\n\n---\n\n## Ethical Framework\n\nHistorical data carries the weight of conquest, displacement, and erasure. AtlasPI is built on four principles that govern every data decision:\n\n### 1. Truth Before Comfort\n\nHistorical 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.\n\n### 2. No Single Version of History\n\nContested 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.\n\n### 3. Transparency of Uncertainty\n\nEvery 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.\n\n### 4. No Geographic or Cultural Bias\n\nPlace 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.\n\n> These principles are enforced through automated ethical tests, documented decisions in `docs/ethics/`, and `# ETHICS:` comments throughout the codebase. See [CLAUDE.md](CLAUDE.md) for the full governance framework.\n\n---\n\n## Architecture\n\n### Tech Stack\n\n| Component | Technology |\n|-----------|------------|\n| API | FastAPI (Python 3.11+) |\n| Database (dev) | SQLite |\n| Database (prod) | PostgreSQL + PostGIS |\n| Validation | Pydantic v2 |\n| Rate Limiting | SlowAPI |\n| Frontend | Vanilla JS + Leaflet.js |\n| Containerization | Docker (multi-stage build) |\n| CI | GitHub Actions (lint + test + build) |\n\n### Project Structure\n\n```\natlaspi/\n src/\n api/ # FastAPI routes, schemas, error handling\n db/ # SQLAlchemy models, database setup, seed data\n ingestion/ # Data import pipelines, boundary extraction\n validation/ # Confidence scoring engine\n static/ # Web UI (HTML, CSS, JS)\n data/\n entities/ # Source entity data (JSON)\n raw/ # Original unmodified source data\n processed/ # Normalized data\n tests/ # 260 tests: technical, ethical, security, performance, data quality\n docs/\n adr/ # Architecture Decision Records\n ethics/ # Documented ethical decisions (ETHICS-001, 002, 003...)\n```\n\n### Key Design Decisions\n\n- **Dual database support:** SQLite for zero-config local development, PostgreSQL + PostGIS for production spatial queries.\n- **Auto-seeding:** The database populates itself on first launch from JSON entity files -- no manual migration needed.\n- **GZip compression**, **CORS**, **rate limiting** (60 req/min), and **security headers** enabled by default.\n- **Structured logging:** JSON format in production, human-readable in development.\n\n---\n\n## Testing\n\nThe test suite covers five dimensions:\n\n```bash\n# Run all tests\npytest\n\n# Run with verbose output\npytest -v\n```\n\n| Category | What it verifies |\n|----------|-----------------|\n| **Technical** | API responses, pagination, input validation, edge cases |\n| **Ethical** | ETHICS-001/002/003 compliance, disputed territory handling, confidence thresholds |\n| **Security** | CORS, security headers, structured error responses, rate limiting |\n| **Performance** | All endpoints respond in < 500ms |\n| **Data Quality** | Source completeness, regional diversity, entity type coverage |\n\n---\n\n## Contributing\n\nContributions are welcome. Before you start:\n\n1. **Read [CLAUDE.md](CLAUDE.md)** -- it contains the project's core values and development conventions.\n2. **Check `docs/ethics/`** -- understand the ethical decisions already made.\n3. **Check `docs/adr/`** -- understand the architectural decisions already made.\n\n### Guidelines\n\n- Code is written in **English**; documentation in **Italian** (except this README).\n- Every function touching sensitive historical data must include an `# ETHICS:` comment explaining the design choice.\n- Tests must cover ethical edge cases, not only technical ones.\n- New entity data must include `sources[]` with verifiable academic citations.\n- Disputed territories must have `confidence_score <= 0.7` and `status: \"disputed\"`.\n\n### Adding Historical Entities\n\nEntity data lives in `data/entities/` as JSON files. Each entity requires:\n- Primary name in the original/local language\n- At least one academic source\n- A confidence score reflecting source reliability\n- Territory changes with dated boundaries where available\n\n### Development Setup\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Lint\nruff check src/ tests/\n\n# Test\npytest -v\n```\n\n---\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for the full development plan. Key upcoming milestones:\n\n- PostgreSQL + PostGIS spatial queries in production\n- Full GeoJSON boundary coverage for all entities\n- Wikidata/OpenStreetMap ingestion pipelines\n- Premium API tier with higher rate limits\n- Hosted instance with public access\n\n---\n\n## How to Cite\n\nIf you use AtlasPI in academic work, teaching, or derivative datasets, please cite it. A machine-readable [`CITATION.cff`](CITATION.cff) is provided in the repository root and is recognized by GitHub, Zenodo, Zotero, and most reference managers.\n\n### Suggested citation (software)\n\n> 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\n\n### BibTeX\n\n```bibtex\n@software{ramadani_atlaspi_2026,\n author = {Ramadani, Clirim},\n title = {AtlasPI: A structured historical geographic database for AI agents},\n version = {6.1.2},\n year = {2026},\n publisher = {CRA},\n doi = {10.5281/zenodo.19581784},\n url = {https://doi.org/10.5281/zenodo.19581784},\n note = {Live instance: https://atlaspi.it. Concept DOI (all versions): 10.5281/zenodo.19581784. Version v6.1.2 DOI: 10.5281/zenodo.19581785.}\n}\n```\n\n### Citing the underlying boundary sources\n\nAtlasPI derives its geographic boundaries from two upstream datasets. If your work depends on spatial precision, please also cite them directly:\n\n- **Natural Earth** (public domain) โ€” post-1800 modern administrative boundaries. https://www.naturalearthdata.com/\n- **aourednik/historical-basemaps** (CC BY 4.0) โ€” pre-1800 historical world timestamps. Ourednik, A. *historical-basemaps*. https://github.com/aourednik/historical-basemaps\n\nFor full methodology on how boundaries are assigned, matched, and confidence-scored, see [docs/METHODOLOGY.md](docs/METHODOLOGY.md).\n\nThe dataset has a permanent DOI minted by Zenodo: [10.5281/zenodo.19581784](https://doi.org/10.5281/zenodo.19581784) (concept DOI, always resolves to the latest version). Every tagged release mints a new version DOI; see the [Zenodo record](https://zenodo.org/records/19581785) for v6.1.2 specifically. Deposition metadata is in [`.zenodo.json`](.zenodo.json).\n\n---\n\n## License\n\nAtlasPI follows an **open core** model.\n\nThe core project -- API, data models, ethical framework, and documentation -- is released under the **Apache License 2.0**.\n\nImported 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.\n\nSee [LICENSE](LICENSE) for the full Apache License 2.0 text and [NOTICE](NOTICE) for third-party attributions.\n\n---\n\n## Acknowledgments\n\nAtlasPI builds on the work of:\n\n- **[Natural Earth](https://www.naturalearthdata.com/)** -- public domain vector map data for modern boundaries\n- **[aourednik/historical-basemaps](https://github.com/aourednik/historical-basemaps)** -- historical world boundary data\n- **[OpenStreetMap](https://www.openstreetmap.org/)** -- geographic data under ODbL\n- **[Wikidata](https://www.wikidata.org/)** -- structured knowledge base under CC0\n\nAnd the countless historians, cartographers, and researchers whose work makes structured historical geography possible.\n\n---\n\n

\n Built with the conviction that historical truth, including its uncomfortable parts, should be structured, accessible, and machine-readable.\n

\n", "bytes": 19819, "sha": "043bd11fbbf8b5f1934a94aa042377e0113323d5f2b504bedd6bf49b74c587f8", "repo_slug": "soil911/atlaspi", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_soil911_atlaspi_1986e8d9/readme" }