Timelory API Documentation

The Timelory REST API provides programmatic access to historical data including empire borders (GeoJSON), dynasty information, ruler genealogies, and timeline structures.

Base URL: https://api.timelory.com/api

Historical Regions API

Access GeoJSON data for historical empire and nation borders.

Query Parameters

Example Request

GET https://api.timelory.com/api/regions/postgis?year=-500

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Achaemenid Empire",
        "start_year": -550,
        "end_year": -330,
        "color": "#8B4513"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[44.0, 33.0], [50.0, 33.0], ...]]
      }
    }
  ]
}

Example Response

{
  "success": true,
  "data": {
    "years": [-3000, -2900, -2800, ..., 2020],
    "minYear": -3000,
    "maxYear": 2020
  }
}

Dynasties API

Access dynasty metadata and ruler information.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "assyrian",
      "name": "Assyrian Empire",
      "description": "Ancient Mesopotamian empire...",
      "startYear": -2025,
      "endYear": -609,
      "capital": "Nineveh",
      "imageUrl": "https://timelory.com/images/assyria.jpg"
    }
  ]
}

Example Response

{
  "success": true,
  "data": [
    {
      "id": "ashurbanipal",
      "name": "Ashurbanipal",
      "title": "King of Assyria",
      "startYear": -669,
      "endYear": -631,
      "description": "Last great Assyrian king...",
      "events": [
        {
          "year": -640,
          "title": "Library of Nineveh",
          "description": "Created greatest cuneiform collection",
          "type": "cultural"
        }
      ]
    }
  ]
}

Timelines API

Access and manage timeline data structures.

Timeline Structure

{
  "id": "assyrian-timeline",
  "name": "Assyrian Empire Timeline",
  "description": "Complete history of Assyria",
  "tracks": [
    {
      "id": "old_assyrian",
      "name": "Old Assyrian Period",
      "startYear": -2025,
      "endYear": -1750,
      "color": "#7C3AED",
      "items": [
        {
          "id": "erishum_i",
          "name": "Erishum I",
          "start": -1974,
          "end": -1935,
          "events": [...]
        }
      ]
    }
  ]
}

Authentication

Most read endpoints are public. Write operations require authentication.

Request Body

{
  "email": "user@example.com",
  "password": "your-password"
}

Using the Token

Authorization: Bearer {token}

Rate Limits

Error Responses

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common Error Codes

SDKs & Libraries

Official SDKs coming soon. For now, use any HTTP client:

// JavaScript/TypeScript
const response = await fetch('https://api.timelory.com/api/regions/postgis?year=-500');
const data = await response.json();

// Python
import requests
response = requests.get('https://api.timelory.com/api/regions/postgis', params={'year': -500})
data = response.json()