AtlasPI API Explorer

Getting Started

AtlasPI is a structured historical geographic database designed for AI agents. It provides coordinates, GeoJSON boundaries, and historical metadata for geopolitical entities across all eras — from 4500 BCE to 2024.

Entities

862+

Events

312+

Dynasty Chains

25+

Academic Sources

2,200+

Base URL & Response Format

Production URL

https://atlaspi.cra-srl.com

Authentication

None (public)

Rate Limit

60 req/min

Format

JSON

Convention: All API endpoints are prefixed with /v1/. Years are integers — negative values represent BCE dates (e.g., -500 = 500 BCE). Every entity includes a confidence_score (0.0-1.0) and sources array.

Example: Quick start with curl

# Get all empires that existed in 1500 CE
curl -s https://atlaspi.cra-srl.com/v1/entity?year=1500&type=empire

# World snapshot for a given year
curl -s https://atlaspi.cra-srl.com/v1/snapshot/1500

# Find entities near Rome
curl -s "https://atlaspi.cra-srl.com/v1/nearby?lat=41.9&lon=12.5&year=100"

# Random entity
curl -s https://atlaspi.cra-srl.com/v1/random

Entities API

Query geopolitical entities (empires, kingdoms, city-states, etc.) with filtering by year, type, continent, and more. Each entity has original-language names, coordinates, GeoJSON boundaries, confidence scores, and academic sources.

GET /v1/entity Search entities with filters ▼

Returns entities filtered by year, type, continent, status, and confidence. Supports pagination.

Parameters

Name	Type	Description
year	int	Filter entities that existed in this year (negative = BCE)
type	string	Entity type: empire, kingdom, city_state, etc.
continent	string	Filter by continent
status	string	confirmed, disputed, approximate
confidence_min	float	Minimum confidence score (0.0-1.0)
limit	int	Results per page (default 50)
offset	int	Pagination offset

Request

curl -s "https://atlaspi.cra-srl.com/v1/entity?year=1200&type=empire&limit=3"

Response

GET /v1/entities List all entities (paginated) ▼

Returns all entities with pagination support. Lighter than /v1/entity when no filters needed.

Parameters

Name	Type	Description
limit	int	Results per page (default 50)
offset	int	Pagination offset

Response

GET /v1/entities/{entity_id} Get entity by ID ▼

Returns full details for a single entity, including GeoJSON boundaries and all metadata.

Parameters

Name	Type	Description
entity_id required	int	Entity ID

Response

GET /v1/snapshot/{year} World snapshot for a year ▼

Returns all entities that existed in the given year, with summary statistics by type and continent.

Parameters

Name	Type	Description
year required	int	Year (negative = BCE)
type	string	Filter by entity type

Response

GET /v1/nearby Entities near coordinates ▼

Find entities near a geographic point, optionally filtered by year.

Parameters

Name	Type	Description
lat required	float	Latitude
lon required	float	Longitude
year	int	Filter by year
radius_km	float	Search radius in km

Response

GET /v1/random Random entity ▼

Returns a random entity from the database. Useful for discovery and testing.

Response

GET /v1/types List entity types ▼

Returns all distinct entity types in the database with counts.

Response

GET /v1/continents List continents ▼

Returns all distinct continents with entity counts.

Response

GET /v1/stats Database statistics ▼

Returns aggregate statistics about the database: total entities, breakdown by type, continent, temporal coverage.

Response

GET /v1/search Search entities by name ▼

Search entities by name (original name, English name, or variants). Returns ranked results.

Parameters

Name	Type	Description
q required	string	Search query
limit	int	Max results (default 10)

Response

Events API

Historical events linked to entities — battles, treaties, conquests, and more. Each event has date precision metadata, geographic coordinates, and ethical annotations.

GET /v1/events List events with filters ▼

Returns historical events filtered by type, year range, entity, and more.

Parameters

Name	Type	Description
event_type	string	battle, treaty, conquest, founding, etc.
year_min	int	Start of year range
year_max	int	End of year range
entity_id	int	Filter by related entity
limit	int	Results per page (default 50)
offset	int	Pagination offset

Response

GET /v1/events/types List event types ▼

Returns all distinct event types with counts.

Response

GET /v1/events/{event_id} Get event by ID ▼

Returns full details for a single historical event.

Parameters

Name	Type	Description
event_id required	int	Event ID

Response

GET /v1/events/on-this-day/{mm_dd} Events on a calendar date ▼

Returns events that occurred on a specific month/day across all years.

Parameters

Name	Type	Description
mm_dd required	string	Month-day format, e.g. "10-14" for Oct 14

Response

GET /v1/entities/{entity_id}/events Events for an entity ▼

Returns all historical events linked to a specific entity.

Parameters

Name	Type	Description
entity_id required	int	Entity ID

Response

Date precision: Events include date_precision field (DAY, MONTH, YEAR, DECADE, CENTURY, APPROXIMATE) indicating how precise the recorded date is. Ancient events often have APPROXIMATE or CENTURY precision.

Cities & Trade Routes API

Historical cities and trade routes with geographic coordinates and temporal data.

GET /v1/cities List historical cities ▼

Returns historical cities with coordinates, founding dates, and associated entities.

Parameters

Name	Type	Description
city_type	string	capital, port, religious, trade_hub, etc.
entity_id	int	Filter by owning entity
limit	int	Results per page

Response

GET /v1/cities/{city_id} Get city by ID ▼

Returns full details for a single city.

Response

GET /v1/routes List trade routes ▼

Returns historical trade routes with waypoints, time periods, and associated entities.

Parameters

Name	Type	Description
route_type	string	land, sea, river
limit	int	Results per page

Response

GET /v1/routes/{route_id} Get route by ID ▼

Returns full details for a single trade route including waypoints.

Response

Dynasty Chains API

Succession chains linking entities across time — dynasty sequences, colonial chains, ideological lineages. Each chain includes transition metadata (type, violence, ethical notes).

GET /v1/chains List all dynasty chains ▼

Returns all dynasty/succession chains with their links. Filterable by type and region.

Parameters

Name	Type	Description
chain_type	string	SUCCESSION, DYNASTY, COLONIAL, IDEOLOGICAL, RESTORATION
region	string	Filter by region

Response

GET /v1/chains/types List chain types ▼

Returns all distinct chain types with counts.

Response

GET /v1/chains/{chain_id} Get chain by ID ▼

Returns full chain details including all links with transition metadata and ethical notes.

Response

GET /v1/entities/{entity_id}/predecessors Entity predecessors in chains ▼

Returns entities that precede the given entity in any dynasty chain.

Response

GET /v1/entities/{entity_id}/successors Entity successors in chains ▼

Returns entities that follow the given entity in any dynasty chain.

Response

Search & Export API

Unified search across all data types and bulk export in CSV, GeoJSON, and JSON formats.

GET /v1/search/advanced Unified search across all data ▼

Search across entities, events, cities, and trade routes. Results ranked by relevance with filters.

Parameters

Name	Type	Description
q required	string	Search query (min 2 chars)
data_type	string	entity, event, city, route
entity_type	string	Filter entities by type
year_min	int	Start of year range
year_max	int	End of year range
status	string	confirmed, disputed, approximate
sort	string	relevance, name, year, confidence
limit	int	Results per page (default 20)
offset	int	Pagination offset

Response

GET /v1/search/fuzzy Fuzzy name search ▼

Tolerant search that handles misspellings and partial matches.

Parameters

Name	Type	Description
q required	string	Search query
limit	int	Max results

Response

GET /v1/export/entities Export entities (CSV/GeoJSON) ▼

Bulk export entities in CSV or GeoJSON format. Max 1000 rows per request.

Parameters

Name	Type	Description
format required	string	csv or geojson
entity_type	string	Filter by type
year_min	int	Start of year range
year_max	int	End of year range

Note: Export endpoints return file downloads (Content-Disposition: attachment). CSV includes UTF-8 BOM for Excel compatibility.

GET /v1/export/events Export events (CSV/JSON) ▼

Bulk export events in CSV or JSON format. Max 1000 rows per request.

Parameters

Name	Type	Description
format required	string	csv or json
event_type	string	Filter by event type
year_min	int	Start of year range
year_max	int	End of year range

Timeline & Compare API

Timeline data for visualization and side-by-side entity comparison.

GET /v1/timeline-data Timeline data for visualization ▼

Returns entity data structured for timeline visualization: start/end years, type, region.

Parameters

Name	Type	Description
region	string	Filter by continent/region
type	string	Filter by entity type
year_min	int	Start of year range
year_max	int	End of year range

Response

GET /v1/compare Compare 2-4 entities ▼

Side-by-side comparison of 2-4 entities with overlap analysis, shared events, and chain context.

Parameters

Name	Type	Description
ids required	string	Comma-separated entity IDs (2-4), e.g. "1,2,3"

Response

GET /v1/compare/{id1}/{id2} Compare two entities (legacy) ▼

Legacy pair comparison. Use /v1/compare?ids= for the newer multi-entity comparison.

Response

Relations API

Explore relationships between entities: contemporaries, related polities, evolution over time.

GET /v1/entities/{entity_id}/contemporaries Entities that existed at the same time ▼

Returns entities with overlapping temporal ranges.

Response

GET /v1/entities/{entity_id}/evolution Entity evolution over time ▼

Returns the temporal evolution of an entity: boundary changes, name changes, type transitions.

Response

GET /v1/entities/{entity_id}/timeline Entity timeline ▼

Returns a timeline of key events and milestones for a specific entity.

Response

Admin & Insights API

Traffic analytics, data coverage reports, and smart suggestions for data expansion.

GET /admin/insights Traffic and usage analytics ▼

Returns traffic analytics: request counts, popular endpoints, geographic distribution, user agents.

Response

GET /admin/coverage-report Data quality and coverage ▼

Comprehensive report on data coverage: temporal gaps, geographic distribution, confidence scores, source quality.

Response

GET /admin/suggestions Smart expansion suggestions ▼

AI-generated suggestions for expanding the dataset: missing entities, underrepresented regions, temporal gaps.

Response

Health Check

System health and diagnostics.

GET /health System health check ▼

Returns system status, version, entity count, database connection status, and uptime.

Example Response

{
  "status": "ok",
  "version": "6.21.0",
  "entity_count": 862,
  "database": {
    "connected": true,
    "type": "postgresql"
  }
}

Response