Documentation

Build with REST APIs, WebSockets, and SDKs

🔗API Reference 📖BMS Guidebook

Getting Started

Welcome to the Retrograde Observatory API documentation. Our APIs provide real-time access to temporal data, enabling you to build applications that understand and adapt to natural time cycles.

REST REST API

Traditional HTTP endpoints for Calculate, SIPS, Vortex, Lumina Map, and Lumina Coordinate.

WS WebSocket API

Real-time bidirectional communication using Socket.IO for live data streaming.

SDK Official SDKs

JavaScript/TypeScript and Python SDKs for rapid integration.

Core Concepts

Behavioral Modulation Signal (BMS)

The BMS is a standardized way to understand and work with timing-aware intelligence. It translates complex temporal patterns into actionable insights:

  • Temporal Position: Your current location within natural time cycles
  • Behavioral Phase: The active state influencing behavior
  • Expression Intensity: How strongly temporal patterns manifest
  • Maturity Level: Long-term developmental trajectory
  • Daily Rhythm: 24-hour behavioral modulation cycle
  • Harmony Score: Alignment between short-term and long-term patterns

Nine Calendars (Elements)

Calendar Code Calendar ID Element Domain
7F7F7Fmonolith-stillnessIndividualityBaseline identity
FF0000crimson-forgeCapacityEffort readiness
FF4000ember-serpentFlexibilityAdaptation
FFFF00solar-loomStabilityConsistency
00FF00emerald-gridContextPerception
00FFC0tidal-compassContinuityDurability
0000FFindigo-exileContentIntrospection
FF00FFtwin-spiralDualityPolarity
606Fouroboric-gateConnectivityIntegration

Choose Your Integration

Feature REST API WebSocket SDKs
Real-time updates
Simple integration ✅✅
Type safety ✅ (TypeScript)
Auto-reconnection N/A

Authentication

All API requests require an API key obtained through the Partner Program. Include it in your requests:

curl -H "x-api-key: YOUR_API_KEY" \
  https://www.retrogradeobservatory.com/api/external/v1/calculate
https://www.retrogradeobservatory.com/api/external/v1/calculate?api_key=YOUR_API_KEY
const socket = io('https://www.retrogradeobservatory.com', {
  path: '/ws',
  auth: { apiKey: 'YOUR_API_KEY' }
});

Rate Limits

Key Type Rate Limit
Demo10 requests per 15 minutes
Standard50 requests per 15 minutes
Premium100 requests per 15 minutes

REST API Reference

Base URL: https://www.retrogradeobservatory.com

POST /api/external/v1/calculate

Calculate personal time intelligence components from birth data and current location.

Request Parameters

ParameterTypeRequiredDescription
birthDatestringYesBirth date (YYYY-MM-DD)
birthTimestringYesBirth time (HH:MM:SS, 24-hour)
latitudenumberYesLocation latitude (-90 to 90)
longitudenumberYesLocation longitude (-180 to 180)
timezonestringRecommendedTimezone offset (e.g., "UTC-05:00")

Example Request

curl -X POST "https://www.retrogradeobservatory.com/api/external/v1/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "birthDate": "1990-01-15",
    "birthTime": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timezone": "UTC-05:00"
  }'

Response

{
  "last": "17:15:28",
  "node": "63",
  "direction": "Levitating",
  "movement": "East-South",
  "season": "Summer",
  "stage": "Action Potential",
  "timeQuadrant": "Disintegrated",
  "scale": "Supra-Human",
  "numericalQuotient": "Quinary",
  "aayu": "1"
}

BMS API - Behavioral Modulation Signals

Base URL: https://os.retrogradeobservatory.com/api/bms/v1

GET /signal

Get BMS signal for current or specified calendar

GET /signals

Get BMS signals for all 9 calendars

POST /signal

Generate BMS signal for specific date/time/location

Tier System

TierPropertiesRate LimitBest For
minimal~7100 req/minMobile apps, widgets
standard~2260 req/minMost applications
full~35+30 req/minRich visualizations
rawAll10 req/minResearch, ML training

Raw SIPS API v1 New

Raw Spatial Intelligence Processing System - Direct coordinate data using single date/time input.

Base URL: /api/rawsips/v1

Coordinate System:

  • X: Primary spatial coordinate
  • Y: Secondary spatial coordinate
  • Z: Tertiary spatial coordinate

Authentication

Requires API key with sips-read permission via x-api-key header.

POST /

Calculate Raw SIPS coordinates for a given birth date/time and location.

Request Body
{
    "action": "fetchAndStoreAllCalendarData",
    "system": {
        "startDate": "1990-01-15",
        "startTime": "14:30",
        "timezone": "UTC-5",
        "latitude": 40.7128,
        "longitude": -74.0060
    },
    "calendars": ["calendar_code_1", "calendar_code_2"]
}
Parameters
FieldTypeRequiredDescription
actionstringYesMust be "fetchAndStoreAllCalendarData"
system.startDatestringYesBirth date in YYYY-MM-DD format
system.startTimestringYesBirth time in HH:MM format
system.timezonestringYesUTC offset (e.g., "UTC+5:30", "UTC-5")
system.latitudenumberYesLatitude (-90 to 90)
system.longitudenumberYesLongitude (-180 to 180)
calendarsarrayYesArray of calendar codes to process
Response
{
    "success": true,
    "results": {
        "7F7F7F": {
            "Calendar": "7F7F7F",
            "scale_X": 45.67,
            "scale_Y": 23.45,
            "scale_Z": -12.34,
            "radial_Location": 52.89,
            "polar_Angle": 27.18,
            "azimuthal_Angle": 76.54,
            "sphericalCoord_area": 35156.78,
            "sphericalCoord_volume": 619842.34,
            "sphericalCoord_Distance": 52.89,
            "sphericalCoord_Angular": 76.54
        }
    }
}
Response Fields
FieldTypeDescription
CalendarstringCalendar code identifier
scale_XnumberX coordinate
scale_YnumberY coordinate
scale_ZnumberZ coordinate
radial_LocationnumberSpherical rho (distance from origin)
polar_AnglenumberSpherical theta (polar angle in degrees)
azimuthal_AnglenumberSpherical phi (azimuthal angle in degrees)
sphericalCoord_areanumberSurface area of sphere with radius rho
sphericalCoord_volumenumberVolume of sphere with radius rho
sphericalCoord_DistancenumberTime spread (distance between positions)
sphericalCoord_AngularnumberTime curve (angular separation)
GET /health

Health check endpoint. No authentication required.

{
    "success": true,
    "status": "operational",
    "api_version": "1.0",
    "service": "Raw SIPS (Raw Singular Identity Positioning System)",
    "uptime": 3600.5
}
GET /version

Version information. No authentication required.

Additional Endpoints: GET /docs, GET /status, GET /elements

Raw Vortex API v1 New

Raw Vortex Intelligence Processing System - Direct coordinate data using single date/time input.

Base URL: /api/rawvortex/v1

Coordinate System:

  • X (span): Primary temporal coordinate
  • Y (era): Secondary temporal coordinate
  • Z (orbit): Tertiary temporal coordinate

Authentication

Requires API key with vortex-read permission via x-api-key header.

POST /

Calculate Raw Vortex coordinates for a given birth date/time and location.

Request Body
{
    "action": "fetchAndStoreAllCalendarData",
    "system": {
        "startDate": "1990-01-15",
        "startTime": "14:30",
        "timezone": "UTC-5",
        "latitude": 40.7128,
        "longitude": -74.0060
    },
    "calendars": ["calendar_code_1", "calendar_code_2"]
}
Parameters

Same parameters as Raw SIPS API. See Raw SIPS section for details.

Response
{
    "success": true,
    "results": {
        "7F7F7F": {
            "Calendar": "7F7F7F",
            "scale_X": 45.67,
            "scale_Z": -12.34,
            "scale_Y": 23.45,
            "radial_Location": 52.89,
            "polar_Angle": 27.18,
            "azimuthal_Angle": 76.54,
            "sphericalCoord_Area": 35156.78,
            "sphericalCoord_Volume": 619842.34,
            "sphericalCoord_Distance": 52.89,
            "sphericalCoord_Angle": 76.54
        }
    }
}
Response Fields
FieldTypeDescription
CalendarstringCalendar code identifier
scale_XnumberX coordinate - mapped as 'span'
scale_ZnumberZ coordinate - mapped as 'orbit'
scale_YnumberY coordinate - mapped as 'era'
radial_LocationnumberSpherical rho (distance from origin)
polar_AnglenumberSpherical theta (polar angle in degrees)
azimuthal_AnglenumberSpherical phi (azimuthal angle in degrees)
sphericalCoord_AreanumberSurface area of sphere with radius rho
sphericalCoord_VolumenumberVolume of sphere with radius rho
sphericalCoord_DistancenumberTime spread (distance between positions)
sphericalCoord_AnglenumberTime curve (angular separation)
GET /health

Health check endpoint. No authentication required.

{
    "success": true,
    "status": "operational",
    "api_version": "1.0",
    "service": "Raw Vortex (Raw Vortex Intelligence Processing System)",
    "uptime": 3600.5
}
GET /version

Version information. No authentication required.

Additional Endpoints: GET /docs, GET /status, GET /elements

Example - JavaScript

const response = await fetch('/api/rawvortex/v1/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here'
    },
    body: JSON.stringify({
        action: 'fetchAndStoreAllCalendarData',
        system: {
            startDate: '1990-01-15',
            startTime: '14:30',
            timezone: 'UTC-5',
            latitude: 40.7128,
            longitude: -74.0060
        },
        calendars: ['7F7F7F', 'FF0000']
    })
});

const data = await response.json();
if (data.success) {
    for (const [calendar, result] of Object.entries(data.results)) {
        console.log(`Span: ${result.scale_X}, Era: ${result.scale_Y}, Orbit: ${result.scale_Z}`);
    }
}

Celestial Body API New

Celestial Body Coordinate System - Calculate coordinate data for 109 celestial bodies including planets, moons, asteroids, comets, and stars.

Two Versions Available:

  • v1 (/api/celestial/v1): Direct time-based positions - instantaneous positions at exact times
  • v2 (/api/celestial/v2): Sidereal Time Reference - isolates orbital motion from Earth's rotation

API v1 - Direct Time-Based Positions

Base URL: /api/celestial/v1

Data Sources:

  • JPL Horizons API: 49 solar system objects (Sun, planets, moons, dwarf planets, asteroids, comets, centaurs, TNOs, Lagrange points)
  • SIMBAD TAP API: 60 named stars from major constellations

Authentication

Requires API key with sips-read permission via x-api-key header.

POST /

Calculate celestial body coordinates for given birth and present times.

Request Body
{
    "action": "fetchAndStoreAllCalendarData",
    "system": {
        "startDate": "1990-01-15",
        "startTime": "14:30",
        "timezone": "+05:30",
        "latitude": 28.6139,
        "longitude": 77.2090
    },
    "celestialBodies": ["moon", "mars", "sirius", "vega"]
}
Parameters
FieldTypeRequiredDescription
actionstringYesMust be "fetchAndStoreAllCalendarData"
system.startDatestringYesBirth date in YYYY-MM-DD format
system.startTimestringYesBirth time in HH:MM format
system.timezonestringYesUTC offset (e.g., "+05:30", "-05:00")
system.latitudenumberYesObserver latitude (-90 to 90)
system.longitudenumberYesObserver longitude (-180 to 180)
system.endDatestringNoPresent date (defaults to now)
system.endTimestringNoPresent time (defaults to now)
celestialBodiesarrayYesArray of celestial body IDs (e.g., ["moon", "sirius"])
Response
{
    "success": true,
    "results": {
        "moon": {
            "celestialBody": "Moon",
            "bodyType": "satellite",
            "scale_X": -50.66,
            "scale_Y": -88.89,
            "scale_Z": 26.75,
            "radial_Location": 105.76,
            "polar_Angle": -119.68,
            "azimuthal_Angle": 75.35,
            "sphericalCoord_area": 140548.57,
            "sphericalCoord_volume": 4954655.36,
            "sphericalCoord_Distance": 503.21,
            "sphericalCoord_Angular": 38.95
        },
        "sirius": {
            "celestialBody": "Sirius",
            "bodyType": "star",
            "scale_X": -18.42,
            "scale_Y": -9.08,
            "scale_Z": 0,
            "radial_Location": 20.54,
            "polar_Angle": -153.78,
            "azimuthal_Angle": 90,
            "sphericalCoord_area": 5300.37,
            "sphericalCoord_volume": 36285.47,
            "sphericalCoord_Distance": 282.13,
            "sphericalCoord_Angular": 100.60
        }
    }
}
Response Fields
FieldTypeDescription
celestialBodystringDisplay name of the celestial body
bodyTypestringType: star, planet, satellite, dwarf_planet, asteroid, comet, centaur, tno, lagrange
scale_XnumberX coordinate
scale_YnumberY coordinate
scale_ZnumberZ coordinate
radial_LocationnumberSpherical rho (distance from origin)
polar_AnglenumberSpherical theta (polar angle in degrees)
azimuthal_AnglenumberSpherical phi (azimuthal angle in degrees)
sphericalCoord_areanumberSurface area of sphere with radius rho
sphericalCoord_volumenumberVolume of sphere with radius rho
sphericalCoord_DistancenumberSpherical distance between birth and present positions
sphericalCoord_AngularnumberAngular separation between birth and present
GET /bodies

List all 109 available celestial bodies grouped by type. No authentication required.

{
    "success": true,
    "api_version": "1.1",
    "count": 109,
    "solarSystemCount": 49,
    "starCount": 60,
    "types": ["star", "satellite", "planet", "dwarf_planet", "asteroid", "comet", "centaur", "tno", "lagrange"],
    "groupedByType": {
        "star": [
            { "id": "sun", "name": "Sun", "source": "JPL Horizons" },
            { "id": "sirius", "name": "Sirius", "source": "SIMBAD", "constellation": "Canis Major" }
        ],
        "planet": [
            { "id": "mars", "name": "Mars", "source": "JPL Horizons" }
        ]
    }
}
GET /health

Health check endpoint. No authentication required.

Additional Endpoints: GET /docs, GET /status, GET /version

Available Celestial Bodies

TypeBodies
PlanetsMercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune
Dwarf PlanetsPluto, Ceres, Eris, Makemake, Haumea
SatellitesMoon, Io, Europa, Ganymede, Callisto, Titan, Enceladus, Mimas, Tethys, Dione, Rhea, Iapetus, Miranda, Ariel, Umbriel, Titania, Oberon, Triton, Charon
AsteroidsVesta, Pallas, Hygiea, Juno
CometsHalley, Encke, Tempel 1
CentaursChiron, Pholus, Nessus
TNOsSedna, Quaoar, Orcus, Varuna, Ixion
StarsSirius, Canopus, Arcturus, Vega, Capella, Rigel, Procyon, Betelgeuse, Polaris, Aldebaran, Antares, Spica, Regulus, Deneb, + 46 more

Example - JavaScript

const response = await fetch('/api/celestial/v1', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here'
    },
    body: JSON.stringify({
        action: 'fetchAndStoreAllCalendarData',
        system: {
            startDate: '1990-01-15',
            startTime: '14:30',
            timezone: '+05:30',
            latitude: 28.6139,
            longitude: 77.2090
        },
        celestialBodies: ['moon', 'mars', 'sirius', 'vega', 'polaris']
    })
});

const data = await response.json();
if (data.success) {
    for (const [bodyId, result] of Object.entries(data.results)) {
        console.log(`${result.celestialBody}: X=${result.scale_X}, Y=${result.scale_Y}, Z=${result.scale_Z}`);
    }
}

API v2 - Sidereal Time Reference

Sidereal Time Reference Algorithm - Calculate celestial body positions using sidereal-locked coordinates that isolate orbital motion from Earth's rotation.

Base URL: /api/celestial/v2

POST /api/celestial/v2

Calculate sidereal-locked celestial body coordinates.

Request Body
{
    "action": "fetchAndStoreAllCalendarData",
    "system": {
        "startDate": "1991-08-30",
        "startTime": "15:35",
        "endDate": "1991-08-31",
        "endTime": "15:35",
        "timezone": "+05:30",
        "latitude": 28.6139,
        "longitude": 77.2090
    },
    "celestialBodies": ["moon", "sirius"]
}
Response
{
    "success": true,
    "results": {
        "moon": {
            "celestialBody": "Moon",
            "bodyType": "satellite",
            "scale_X": -15.086,
            "scale_Y": -6.737,
            "scale_Z": -3.596,
            "radial_Location": 16.909,
            "polar_Angle": -155.937,
            "azimuthal_Angle": 102.279,
            "sphericalCoord_area": 3592.96,
            "sphericalCoord_volume": 20251.28,
            "sphericalCoord_Distance": 82.20,
            "sphericalCoord_Angular": 11.77
        },
        "sirius": {
            "celestialBody": "Sirius",
            "bodyType": "star",
            "scale_X": 0,
            "scale_Y": 0,
            "scale_Z": 0
        }
    }
}
Understanding v2 Results

Stars Show Near-Zero Changes: Stars are "fixed" in the sky over human timescales. This confirms the sidereal reference is working correctly.

Planets Show Orbital Motion: Fast-moving bodies like the Moon (~13°/day) show significant changes, while slow bodies show minimal changes.

v2 Public Endpoints

GET /api/celestial/v2/bodies, GET /api/celestial/v2/health, GET /api/celestial/v2/docs, GET /api/celestial/v2/version

v2 Example - JavaScript
const response = await fetch('/api/celestial/v2', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here'
    },
    body: JSON.stringify({
        action: 'fetchAndStoreAllCalendarData',
        system: {
            startDate: '1991-08-30',
            startTime: '15:35',
            timezone: '+05:30',
            latitude: 28.6139,
            longitude: 77.2090
        },
        celestialBodies: ['moon', 'mars', 'sirius']
    })
});

const data = await response.json();
console.log('Moon orbital motion:', data.results.moon.scale_X);

Celestial Map API New

Temporal Coordinate Calculations for Celestial Bodies - Two complementary APIs that transform astronomical positions into personalized 3D temporal coordinates.

Two APIs, Different Outputs:

  • Celestial Location API (/api/celestiallocation/v1) - Temporal Location based on Micro Timestamp, outputs temporal_location (Location) & temporal_distance (Distance)
  • Celestial Station API (/api/celestialstation/v1) - Temporal Station based on Macro Timestamp, outputs temporal_station (Station) & temporal_shift (Shift)

Authentication

Celestial Location API requires celestial-location permission. Celestial Station API requires celestial-station permission.

Celestial Location API v1

Base URL: /api/celestiallocation/v1

POST /

Calculate temporal location and distance for celestial bodies.

Request Body
{
    "startDate": "1990-05-20",
    "startTime": "08:00",
    "timezone": "UTC-5",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "endDate": "2024-12-20",
    "endTime": "14:30",
    "celestialBodies": ["mars", "jupiter", "sirius"],
    "format": "standard"
}
Parameters
FieldTypeRequiredDescription
startDatestringYesBirth/start date (YYYY-MM-DD)
startTimestringYesBirth/start time (HH:MM)
timezonestringYesUTC offset (e.g., UTC-5, UTC+5:30)
latitudenumberYesObserver latitude (-90 to 90)
longitudenumberYesObserver longitude (-180 to 180)
celestialBodiesarrayYesArray of celestial body IDs
endDatestringNoPresent date (defaults to now)
endTimestringNoPresent time (defaults to now)
formatstringNoResponse format: standard, compact, partner
Response
{
    "success": true,
    "api_version": "1.0",
    "service": "Celestial Location",
    "mode": "celestial_bodies",
    "results": {
        "Mars": {
            "celestialBody": "Mars",
            "bodyType": "planet",
            "temporal_location": 45.67,
            "temporal_distance": 23.45,
            "spherical_coordinates": {
                "rho": 45.67,
                "theta_deg": 32.5,
                "phi_deg": 67.8
            },
            "inter_body_distances": {
                "Jupiter": 15.23
            }
        },
        "Jupiter": { ... },
        "Sirius": { ... }
    },
    "metadata": {
        "calculation_type": "Temporal Location + Temporal Distance + Inter-Body Distances",
        "terminology": {
            "temporal_location": "Present coordinate value (Location)",
            "temporal_distance": "Distance from birth to present coordinates"
        }
    }
}
Response Fields
FieldTypeDescription
temporal_locationnumberLocation - Present coordinate value (rho) in 3D space
temporal_distancenumberDistance - Spherical distance from birth to present coordinates
spherical_coordinatesobjectFull spherical coordinates (rho, theta, phi)
inter_body_distancesobjectDistances between this body and other requested bodies

Celestial Station API v1

Base URL: /api/celestialstation/v1

POST /

Calculate temporal station and shift for celestial bodies.

Request Body
{
    "startDate": "1990-05-20",
    "startTime": "08:00",
    "timezone": "UTC-5",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "endDate": "2024-12-20",
    "endTime": "14:30",
    "celestialBodies": ["mars", "jupiter", "sirius"],
    "format": "standard"
}
Response
{
    "success": true,
    "api_version": "1.0",
    "service": "Celestial Station",
    "celestial_bodies": {
        "Mars": {
            "celestial_body": "Mars",
            "body_key": "mars",
            "temporal_station": 38.92,
            "temporal_shift": 19.45,
            "elapsedNodes": 5765432,
            "presentNode": 128,
            "interBodyShift": {
                "Jupiter": 12.34
            }
        },
        "Jupiter": { ... },
        "Sirius": { ... }
    },
    "metadata": {
        "calculation_type": "Temporal Station + Temporal Shift + Inter-Body Shifts",
        "terminology": {
            "temporal_station": "Station - Present coordinate value in 3D space",
            "temporal_shift": "Shift - Distance from birth to present coordinates"
        }
    }
}
Response Fields
FieldTypeDescription
temporal_stationnumberStation - Present coordinate value (rho) in 3D space
temporal_shiftnumberShift - Spherical distance from birth to present coordinates
elapsedNodesnumberTotal elapsed time nodes
presentNodenumberCurrent time node
interBodyShiftobjectShifts between this body and other requested bodies

Public Endpoints (No Auth Required)

EndpointDescription
GET /api/celestiallocation/v1/bodiesList all 114 available celestial bodies
GET /api/celestiallocation/v1/healthAPI health check
GET /api/celestiallocation/v1/docsAPI documentation
GET /api/celestialstation/v1/bodiesList all 114 available celestial bodies
GET /api/celestialstation/v1/healthAPI health check
GET /api/celestialstation/v1/docsAPI documentation

Supported Celestial Bodies (114 Total)

CategoryCountExamples
Planets7mercury, venus, mars, jupiter, saturn, uranus, neptune
Dwarf Planets5pluto, ceres, eris, makemake, haumea
Major Satellites9moon, io, europa, ganymede, callisto, titan, triton
Asteroids & Centaurs7vesta, pallas, chiron, pholus, nessus
Trans-Neptunian Objects5sedna, quaoar, orcus, varuna, ixion
Comets3halley, encke, tempel1
Stars63sirius, canopus, arcturus, vega, rigel, betelgeuse, polaris

Example - JavaScript

// Celestial Location API
const locationResponse = await fetch('/api/celestiallocation/v1', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here'
    },
    body: JSON.stringify({
        startDate: '1990-05-20',
        startTime: '08:00',
        timezone: 'UTC-5',
        latitude: 40.7128,
        longitude: -74.0060,
        celestialBodies: ['mars', 'jupiter', 'sirius']
    })
});

const locationData = await locationResponse.json();
console.log('Mars Location:', locationData.results.Mars.temporal_location);
console.log('Mars Distance:', locationData.results.Mars.temporal_distance);

// Celestial Station API
const stationResponse = await fetch('/api/celestialstation/v1', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here'
    },
    body: JSON.stringify({
        startDate: '1990-05-20',
        startTime: '08:00',
        timezone: 'UTC-5',
        latitude: 40.7128,
        longitude: -74.0060,
        celestialBodies: ['mars', 'jupiter', 'sirius']
    })
});

const stationData = await stationResponse.json();
console.log('Mars Station:', stationData.celestial_bodies.Mars.temporal_station);
console.log('Mars Shift:', stationData.celestial_bodies.Mars.temporal_shift);

Example - Python

import requests

# Celestial Location API
location_response = requests.post(
    'https://www.retrogradeobservatory.com/api/celestiallocation/v1',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'startDate': '1990-05-20',
        'startTime': '08:00',
        'timezone': 'UTC-5',
        'latitude': 40.7128,
        'longitude': -74.0060,
        'celestialBodies': ['mars', 'jupiter', 'sirius']
    }
)

location_data = location_response.json()
print(f"Mars Location: {location_data['results']['Mars']['temporal_location']}")
print(f"Mars Distance: {location_data['results']['Mars']['temporal_distance']}")

# Celestial Station API
station_response = requests.post(
    'https://www.retrogradeobservatory.com/api/celestialstation/v1',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'startDate': '1990-05-20',
        'startTime': '08:00',
        'timezone': 'UTC-5',
        'latitude': 40.7128,
        'longitude': -74.0060,
        'celestialBodies': ['mars', 'jupiter', 'sirius']
    }
)

station_data = station_response.json()
print(f"Mars Station: {station_data['celestial_bodies']['Mars']['temporal_station']}")
print(f"Mars Shift: {station_data['celestial_bodies']['Mars']['temporal_shift']}")

WebSocket API Real-time

Connect to real-time temporal data using Socket.IO WebSocket connections.

WebSocket Endpoint: wss://www.retrogradeobservatory.com/ws

Connection

Connect using Socket.IO with API key authentication:

import { io } from 'socket.io-client';

const socket = io('https://www.retrogradeobservatory.com', {
  path: '/ws',
  auth: { apiKey: 'YOUR_API_KEY' },
  transports: ['websocket']
});

socket.on('connected', (data) => {
  console.log('Connected:', data.socketId);
  console.log('Permissions:', data.permissions);
});

socket.on('auth:error', (error) => {
  console.error('Auth failed:', error.message);
});
import socketio

sio = socketio.AsyncClient()

@sio.on('connected')
async def on_connected(data):
    print(f"Connected: {data['socketId']}")
    print(f"Permissions: {data['permissions']}")

@sio.on('auth:error')
async def on_auth_error(error):
    print(f"Auth failed: {error['message']}")

await sio.connect(
    'https://www.retrogradeobservatory.com',
    socketio_path='/ws',
    auth={'apiKey': 'YOUR_API_KEY'},
    transports=['websocket']
)

Available Events

HandlerRequest EventResponse EventsPermission
Calculatecalculate:requestcalculate:response, calculate:errorcalculate
Raw SIPSrawsips:requestrawsips:response, rawsips:errorsips-read
Raw Vortexrawvortex:requestrawvortex:response, rawvortex:errorvortex-read
Celestial Bodycelestial:requestcelestial:response, celestial:errorsips-read
Celestial Body (v2)celestial:v2:requestcelestial:v2:response, celestial:v2:errorsips-read
Celestial Locationcelestiallocation:requestcelestiallocation:response, celestiallocation:errorcelestial-location
Celestial Stationcelestialstation:requestcelestialstation:response, celestialstation:errorcelestial-station

calculate:request

// Send request
socket.emit('calculate:request', {
  requestId: 'unique-id',
  birthDate: '1990-05-15',
  birthTime: '14:30',
  timezone: 'UTC-05:00',
  latitude: 40.7128,
  longitude: -74.0060
});

// Listen for response
socket.on('calculate:response', (data) => {
  console.log('Last:', data.last);      // "12:08:20"
  console.log('Node:', data.node);      // "242"
  console.log('Direction:', data.direction);  // "Gravitating"
});

rawsips:request sips-read New

Returns raw coordinate data (scale_X, scale_Y, scale_Z, radial_Location, etc.) without card mappings. WebSocket equivalent of POST /api/rawsips/v1.

Request
socket.emit('rawsips:request', {
  action: 'fetchAndStoreAllCalendarData',
  system: {
    startDate: '1990-01-15',
    startTime: '14:30',
    timezone: 'UTC-5',
    latitude: 40.7128,
    longitude: -74.0060
  },
  calendars: ['7F7F7F', 'FF0000']
});
Response
socket.on('rawsips:response', (data) => {
  // data.results contains:
  // {
  //   "7F7F7F": {
  //     "Calendar": "7F7F7F",
  //     "scale_X": 45.67,
  //     "scale_Y": 23.45,
  //     "scale_Z": -12.34,
  //     "radial_Location": 52.89,
  //     "polar_Angle": 27.18,
  //     "azimuthal_Angle": 76.54,
  //     "sphericalCoord_area": 35156.78,
  //     "sphericalCoord_volume": 619842.34,
  //     "sphericalCoord_Distance": 52.89,
  //     "sphericalCoord_Angular": 76.54
  //   }
  // }
  console.log('Raw SIPS:', data.results);
});

socket.on('rawsips:error', (error) => {
  console.error('Error:', error.message);
});
Response Fields
FieldDescription
scale_XX coordinate
scale_YY coordinate
scale_ZZ coordinate
radial_LocationSpherical rho (distance from origin)
polar_AngleSpherical theta (degrees)
azimuthal_AngleSpherical phi (degrees)
sphericalCoord_areaSurface area of sphere
sphericalCoord_volumeVolume of sphere
sphericalCoord_DistanceTime spread
sphericalCoord_AngularTime curve

rawvortex:request vortex-read New

Returns raw coordinate data. WebSocket equivalent of POST /api/rawvortex/v1.

Request
socket.emit('rawvortex:request', {
  action: 'fetchAndStoreAllCalendarData',
  system: {
    startDate: '1990-01-15',
    startTime: '14:30',
    timezone: 'UTC-5',
    latitude: 40.7128,
    longitude: -74.0060
  },
  calendars: ['7F7F7F', 'FF0000']
});
Response
socket.on('rawvortex:response', (data) => {
  // data.results contains:
  // {
  //   "7F7F7F": {
  //     "Calendar": "7F7F7F",
  //     "scale_X": 45.67,
  //     "scale_Z": -12.34,
  //     "scale_Y": 23.45,
  //     "radial_Location": 52.89,
  //     "polar_Angle": 27.18,
  //     "azimuthal_Angle": 76.54,
  //     "sphericalCoord_Area": 35156.78,
  //     "sphericalCoord_Volume": 619842.34,
  //     "sphericalCoord_Distance": 52.89,
  //     "sphericalCoord_Angle": 76.54
  //   }
  // }
  console.log('Raw Vortex:', data.results);
});

socket.on('rawvortex:error', (error) => {
  console.error('Error:', error.message);
});
Response Fields
FieldDescription
scale_XX coordinate - span
scale_ZZ coordinate - orbit
scale_YY coordinate - era
radial_LocationSpherical rho (distance from origin)
polar_AngleSpherical theta (degrees)
azimuthal_AngleSpherical phi (degrees)
sphericalCoord_AreaSurface area of sphere
sphericalCoord_VolumeVolume of sphere
sphericalCoord_DistanceTime spread
sphericalCoord_AngleTime curve

celestial:request sips-read New

Calculate coordinates for 109 celestial bodies including planets, moons, asteroids, comets, and stars. WebSocket equivalent of POST /api/celestial/v1.

Request
socket.emit('celestial:request', {
  action: 'fetchAndStoreAllCalendarData',
  system: {
    startDate: '1990-01-15',
    startTime: '14:30',
    timezone: '+05:30',
    latitude: 28.6139,
    longitude: 77.2090
  },
  celestialBodies: ['moon', 'mars', 'sirius', 'vega']
});
Response
socket.on('celestial:response', (data) => {
  // data.results contains:
  // {
  //   "moon": {
  //     "celestialBody": "Moon",
  //     "bodyType": "satellite",
  //     "scale_X": -50.66,
  //     "scale_Y": -88.89,
  //     "scale_Z": 26.75,
  //     "radial_Location": 105.76,
  //     "polar_Angle": -119.68,
  //     "azimuthal_Angle": 75.35,
  //     "sphericalCoord_area": 140548.57,
  //     "sphericalCoord_volume": 4954655.36,
  //     "sphericalCoord_Distance": 503.21,
  //     "sphericalCoord_Angular": 38.95
  //   },
  //   "sirius": {
  //     "celestialBody": "Sirius",
  //     "bodyType": "star",
  //     ...
  //   }
  // }
  console.log('Celestial Bodies:', data.results);
});

socket.on('celestial:error', (error) => {
  console.error('Error:', error.message);
});
Response Fields
FieldDescription
celestialBodyDisplay name of the celestial body
bodyTypeType: star, planet, satellite, dwarf_planet, asteroid, comet, centaur, tno, lagrange
scale_XX coordinate
scale_YY coordinate
scale_ZZ coordinate
radial_LocationSpherical rho (distance from origin)
polar_AngleSpherical theta (degrees)
azimuthal_AngleSpherical phi (degrees)
sphericalCoord_areaSurface area of sphere
sphericalCoord_volumeVolume of sphere
sphericalCoord_DistanceSpherical distance between birth and present
sphericalCoord_AngularAngular separation between birth and present
Get Available Bodies

To get a list of all 109 available celestial bodies, emit the celestial:bodies event:

socket.emit('celestial:bodies');

socket.on('celestial:bodies:response', (data) => {
  console.log(`Available: ${data.count} bodies`);
  console.log('Solar System:', data.solarSystemCount);
  console.log('Stars:', data.starCount);
  console.log('Types:', data.types);
});

celestial:v2:request sips-read New

Celestial Body API v2 isolates celestial body orbital motion from Earth's rotation using the Sidereal Time Reference Algorithm. WebSocket equivalent of POST /api/celestial/v2.

Request
socket.emit('celestial:v2:request', {
  action: 'fetchAndStoreAllCalendarData',
  system: {
    startDate: '1991-08-30',    // Birth date
    startTime: '15:35',          // Birth time
    endDate: '2025-12-19',       // Present date (optional, defaults to now)
    endTime: '12:00',            // Present time (optional, defaults to now)
    timezone: '+05:30',
    latitude: 28.6139,
    longitude: 77.2090
  },
  celestialBodies: ['moon', 'mars', 'sirius', 'vega']
});
Response
socket.on('celestial:v2:response', (data) => {
  // data.results contains:
  // {
  //   "moon": {
  //     "celestialBody": "Moon",
  //     "bodyType": "satellite",
  //     "scale_X": -15.08,
  //     "scale_Y": -6.73,
  //     "scale_Z": -3.59,
  //     "radial_Location": 16.90,
  //     "polar_Angle": -155.93,
  //     "azimuthal_Angle": 102.27,
  //     "sphericalCoord_area": 3592.96,
  //     "sphericalCoord_volume": 20251.28,
  //     "sphericalCoord_Distance": 82.20,
  //     "sphericalCoord_Angular": 11.76
  //   }
  // }
  console.log('Celestial Body v2:', data.results);
});

socket.on('celestial:v2:error', (error) => {
  console.error('Error:', error.message);
});
Response Fields
FieldDescription
celestialBodyDisplay name of the celestial body
bodyTypeType: star, planet, satellite, dwarf_planet, asteroid, comet, centaur, tno, lagrange
scale_XX coordinate
scale_YY coordinate
scale_ZZ coordinate
radial_LocationSpherical rho (distance from origin)
polar_AngleSpherical theta (degrees)
azimuthal_AngleSpherical phi (degrees)
sphericalCoord_areaSurface area of sphere
sphericalCoord_volumeVolume of sphere
sphericalCoord_DistanceSpherical distance between birth and present
sphericalCoord_AngularAngular separation between birth and present
Get Available Bodies

To get a list of all 109 available celestial bodies, emit the celestial:v2:bodies event:

socket.emit('celestial:v2:bodies');

socket.on('celestial:v2:bodies:response', (data) => {
  console.log(`Available: ${data.count} bodies`);
  console.log('Solar System:', data.solarSystemCount);
  console.log('Stars:', data.starCount);
  console.log('Types:', data.types);
});

Celestial Map New

Real-time celestial coordinate calculations with two complementary APIs for temporal mapping.

Two APIs, Different Outputs:

  • celestiallocation:* - Location & Distance (requires celestial-location permission)
  • celestialstation:* - Station & Shift (requires celestial-station permission)

celestiallocation:request celestial-location

Calculate temporal location and distance. WebSocket equivalent of POST /api/celestiallocation/v1.

Request
socket.emit('celestiallocation:request', {
  startDate: '1990-05-20',
  startTime: '08:00',
  timezone: 'UTC-5',
  latitude: 40.7128,
  longitude: -74.0060,
  celestialBodies: ['mars', 'jupiter', 'sirius'],
  endDate: '2024-12-20',    // Optional, defaults to now
  endTime: '14:30'          // Optional, defaults to now
});
Response
socket.on('celestiallocation:response', (data) => {
  // data.results contains:
  // {
  //   "Mars": {
  //     "celestialBody": "Mars",
  //     "bodyType": "planet",
  //     "temporal_location": 45.67,
  //     "temporal_distance": 23.45,
  //     "spherical_coordinates": { rho: 45.67, theta_deg: 32.5, phi_deg: 67.8 },
  //     "inter_body_distances": { "Jupiter": 15.23 }
  //   }
  // }
  console.log('Mars Location:', data.results.Mars.temporal_location);
  console.log('Mars Distance:', data.results.Mars.temporal_distance);
});

socket.on('celestiallocation:error', (error) => {
  console.error('Error:', error.message);
});
Response Fields
FieldDescription
temporal_locationLocation - Present coordinate value (rho) in 3D space
temporal_distanceDistance - Spherical distance from birth to present coordinates
spherical_coordinatesFull spherical coordinates (rho, theta, phi)
inter_body_distancesDistances between celestial bodies
Get Available Bodies
socket.emit('celestiallocation:bodies');

socket.on('celestiallocation:bodies:response', (data) => {
  console.log(`Total: ${data.total_count.total} bodies`);
  console.log('Solar System:', data.total_count.solar_system);
  console.log('Stars:', data.total_count.stars);
});

celestialstation:request celestial-station

Calculate temporal station and shift. WebSocket equivalent of POST /api/celestialstation/v1.

Request
socket.emit('celestialstation:request', {
  startDate: '1990-05-20',
  startTime: '08:00',
  timezone: 'UTC-5',
  latitude: 40.7128,
  longitude: -74.0060,
  celestialBodies: ['mars', 'jupiter', 'sirius'],
  endDate: '2024-12-20',    // Optional, defaults to now
  endTime: '14:30'          // Optional, defaults to now
});
Response
socket.on('celestialstation:response', (data) => {
  // data.celestial_bodies contains:
  // {
  //   "Mars": {
  //     "celestial_body": "Mars",
  //     "body_key": "mars",
  //     "temporal_station": 38.92,
  //     "temporal_shift": 19.45,
  //     "elapsedNodes": 5765432,
  //     "presentNode": 128,
  //     "interBodyShift": { "Jupiter": 12.34 }
  //   }
  // }
  console.log('Mars Station:', data.celestial_bodies.Mars.temporal_station);
  console.log('Mars Shift:', data.celestial_bodies.Mars.temporal_shift);
});

socket.on('celestialstation:error', (error) => {
  console.error('Error:', error.message);
});
Response Fields
FieldDescription
temporal_stationStation - Present coordinate value (rho) in 3D space
temporal_shiftShift - Spherical distance from birth to present coordinates
elapsedNodesTotal elapsed time nodes
presentNodeCurrent time node
interBodyShiftShifts between celestial bodies
Get Available Bodies
socket.emit('celestialstation:bodies');

socket.on('celestialstation:bodies:response', (data) => {
  console.log(`Total: ${data.total_count.total} bodies`);
  console.log('Solar System:', data.total_count.solar_system);
  console.log('Stars:', data.total_count.stars);
});

Event Reference

Request EventResponse EventsPermission
celestiallocation:requestcelestiallocation:response, celestiallocation:errorcelestial-location
celestiallocation:bodiescelestiallocation:bodies:response-
celestiallocation:healthcelestiallocation:health:response-
celestialstation:requestcelestialstation:response, celestialstation:errorcelestial-station
celestialstation:bodiescelestialstation:bodies:response-
celestialstation:healthcelestialstation:health:response-

BMS WebSocket Stream AI/ML

Real-time streaming of Behavioral Modulation Signals (BMS) for AI/ML integration.

WebSocket Endpoint: wss://os.retrogradeobservatory.com/api/bms/v1/stream

Quick Start

import asyncio
import json
import websockets

async def bms_stream():
    uri = "wss://os.retrogradeobservatory.com/api/bms/v1/stream"

    async with websockets.connect(uri) as ws:
        # Wait for connection acknowledgment
        connected = json.loads(await ws.recv())
        print(f"Connected: {connected['connectionId']}")

        # Subscribe to BMS stream
        await ws.send(json.dumps({
            "type": "subscribe",
            "apiKey": "your-api-key",
            "config": {
                "tier": "standard",
                "calendars": ["all"],
                "interval": 5000
            }
        }))

        # Receive subscription confirmation
        subscribed = json.loads(await ws.recv())
        print(f"Subscribed: {subscribed}")

        # Listen for BMS signals
        while True:
            msg = json.loads(await ws.recv())
            if msg["type"] == "bms":
                for calendar_id, signal in msg["signals"].items():
                    print(f"{calendar_id}: density={signal['density']:.2f}")

asyncio.run(bms_stream())
const WebSocket = require('ws');

const ws = new WebSocket('wss://os.retrogradeobservatory.com/api/bms/v1/stream');

ws.on('open', () => console.log('Connected to BMS WebSocket'));

ws.on('message', (data) => {
  const msg = JSON.parse(data);

  if (msg.type === 'connected') {
    // Subscribe after connection
    ws.send(JSON.stringify({
      type: 'subscribe',
      apiKey: 'your-api-key',
      config: {
        tier: 'standard',
        calendars: ['all'],
        interval: 5000
      }
    }));
  }

  if (msg.type === 'bms') {
    // Process BMS signals
    console.log(`Sequence ${msg.sequence}:`, Object.keys(msg.signals));
  }
});

ws.on('error', console.error);
ws.on('close', () => console.log('Disconnected'));

Connection Flow

  1. Client connects to WebSocket endpoint
  2. Server sends connected message with available options
  3. Client sends subscribe message with API key and config
  4. Server sends subscribed confirmation
  5. Server pushes bms messages at configured interval
  6. Client can send update to change config or unsubscribe to stop

Subscribe Message

{
  "type": "subscribe",
  "apiKey": "your-api-key",
  "config": {
    "tier": "standard",
    "calendars": ["crimson-forge", "solar-loom"],
    "interval": 5000,
    "params": {
      "date": "2024-03-15",
      "time": "14:30",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "timezone": "UTC-05:00"
    }
  }
}

Configuration Options

FieldTypeRequiredDescription
typestringYesMust be "subscribe"
apiKeystringYesYour API key
config.tierstringNo"minimal", "standard", "full", "raw" (default: "standard")
config.calendarsstring[]NoCalendar IDs or ["all"] (default: all 9 calendars)
config.intervalnumberNoPush interval in ms: 1000, 5000, 10000 (default: 5000)
config.paramsobjectNoCustom date/time/location parameters

BMS Signal Response

{
  "type": "bms",
  "timestamp": "2024-03-15T14:30:05.000Z",
  "sequence": 12,
  "tier": "standard",
  "signals": {
    "crimson-forge": {
      "calendarId": "crimson-forge",
      "aspect": "Capacity",
      "colorHex": "#FF0000",
      "density": 1.15,
      "brightness": 0.82,
      "visibility": 0.88,
      "rhythmScale": 1.12,
      "spatialX": 0.65,
      "spatialY": 0.52,
      "spatialZ": 0.48,
      "cohesiveness": 0.78,
      "wobbleScale": 0.35,
      "interactionDepth": 0.62,
      "responsiveness": 0.55,
      "rotationalVelocity": 1.08,
      "magneticPull": 0.48,
      "auraRadius": 1.62,
      "harmonyGlow": 1.15,
      "formSolidity": 1.05,
      "stageModifier": 1.02
    }
  },
  "meta": {
    "generationTimeMs": 8,
    "nextPushMs": 5000,
    "calendarCount": 9
  }
}

Tier System & Rate Limits

TierPropertiesMessages/MinMin IntervalBest For
minimal71201000msMobile apps, simple LLM prompts
standard22605000msMost AI/ML applications
full35+305000msRich avatar systems, game NPCs
rawAll1210000msML training, research

Tier Data Details

  • Minimal: calendarId, aspect, colorHex, density, brightness, visibility, rhythmScale
  • Standard: Minimal + spatial, interaction, and visual properties
  • Full: Standard + advanced physics, animation, and mood data
  • Raw: Full + harmony analysis, maturity analysis, comprehensive analysis

LLM Integration Example

Use BMS signals to modulate LLM personality in real-time:

def create_llm_context(bms_signals):
    """Convert BMS signals to LLM personality context"""
    primary = bms_signals.get('crimson-forge', {})

    energy_level = primary.get('density', 1.0)
    expressiveness = primary.get('brightness', 0.7)
    stability = primary.get('cohesiveness', 0.7)
    responsiveness = primary.get('responsiveness', 0.5)

    # Map to personality traits
    if energy_level > 1.1:
        tone = "energetic and enthusiastic"
    elif energy_level < 0.9:
        tone = "calm and measured"
    else:
        tone = "balanced and steady"

    context = f"""
    Current behavioral state:
    - Tone: {tone}
    - Expressiveness: {'high' if expressiveness > 0.7 else 'moderate'}
    - Stability: {'stable' if stability > 0.7 else 'dynamic'}
    - Response speed: {'quick' if responsiveness > 0.6 else 'thoughtful'}

    Adjust your responses to match this behavioral profile.
    """

    return context

Other Messages

Update Config

{ "type": "update", "config": { "tier": "full", "interval": 1000 } }

Unsubscribe

{ "type": "unsubscribe" }

Ping (Keep-alive)

{ "type": "ping", "timestamp": 1699876543210 }

Error Codes

CodeDescription
AUTH_FAILEDInvalid or missing API key
INVALID_MESSAGEMalformed JSON or unknown message type
INVALID_CONFIGInvalid subscription configuration
RATE_LIMITEDRate limit exceeded
RATE_THROTTLEDTemporarily throttled (warning)
MAX_CONNECTIONSServer connection limit reached
MAX_CONNECTIONS_PER_IPPer-IP connection limit reached (max 10)
SIGNAL_ERRORFailed to generate BMS signal

Official SDKs New

Use our official SDKs for the fastest integration with type safety and built-in error handling.

📦 @retrograde/observatory-sdk

JavaScript/TypeScript SDK with full type definitions, auto-reconnection, and event-driven architecture.

npm install @retrograde/observatory-sdk

🐍 retrograde-observatory-sdk

Python SDK with async support, decorator-based event handling, and context manager support.

pip install retrograde-observatory-sdk

🌟 @retrograde/lumina-sdk

JS/TS SDK for BMS streams. Real-time behavioral signals for AI/ML integration.

npm install @retrograde/lumina-sdk

🐍 retrograde-lumina-sdk

Python SDK for BMS streams with async iterators and dataclass types.

pip install retrograde-lumina-sdk

JavaScript/TypeScript SDK

Installation

npm install @retrograde/observatory-sdk
# or
yarn add @retrograde/observatory-sdk

Quick Start

import { RetrogradeClient } from '@retrograde/observatory-sdk';

const client = new RetrogradeClient({
  apiKey: 'your-api-key',
  debug: true
});

// Listen for responses
client.on('calculate:response', (data) => {
  console.log('Last:', data.last);
  console.log('Node:', data.node);
  console.log('Direction:', data.direction);
});

client.on('calculate:error', (error) => {
  console.error('Error:', error.message);
});

// Connect and make requests
await client.connect();

await client.calculate({
  birthDate: '1990-05-15',
  birthTime: '14:30',
  timezone: 'UTC-05:00',
  latitude: 40.7128,
  longitude: -74.0060
});

Available Methods

MethodPermissionDescription
calculate()calculateCore temporal calculations
fetchRawSIPS()sips-readRaw SIPS coordinate data
fetchRawVortex()vortex-readRaw Vortex coordinate data
fetchCelestialBodies()sips-readCelestial body coordinates (109 bodies)
getCelestialBodiesList()-List all available celestial bodies
fetchCelestialBodyV2()sips-readCelestial Body v2 (sidereal-referenced)
getCelestialBodyV2BodiesList()-List available bodies for Celestial Body v2 API
fetchCelestialLocation()celestial-locationCelestial Map - Location & Distance
getCelestialLocationBodiesList()-List available bodies for Location API
getCelestialLocationHealth()-Health check for Location API
fetchCelestialStation()celestial-stationCelestial Map - Station & Shift
getCelestialStationBodiesList()-List available bodies for Station API
getCelestialStationHealth()-Health check for Station API

Connection Methods

MethodDescription
connect()Connect to WebSocket server
disconnect()Disconnect from server
isConnected()Check connection status
getState()Get full connection state
getPermissions()Get available permissions
hasPermission(perm)Check specific permission
on(event, callback)Register event listener
off(event, callback)Remove event listener
once(event, callback)One-time listener

Configuration Options

const client = new RetrogradeClient({
  // Required
  apiKey: 'your-api-key',

  // Optional
  url: 'https://www.retrogradeobservatory.com', // WebSocket URL
  path: '/ws',                                   // Socket.IO path
  autoReconnect: true,                           // Auto-reconnect on disconnect
  maxReconnectAttempts: 5,                       // Max reconnection attempts
  debug: false,                                  // Enable debug logging
});

Python SDK

Installation

pip install retrograde-observatory-sdk

Quick Start

import asyncio
from retrograde_sdk import RetrogradeClient

async def main():
    client = RetrogradeClient(api_key="your-api-key", debug=True)

    # Listen for responses
    @client.on("calculate:response")
    def on_calculate(data):
        print(f"Last: {data['last']}")
        print(f"Node: {data['node']}")
        print(f"Direction: {data['direction']}")

    @client.on("calculate:error")
    def on_error(error):
        print(f"Error: {error['message']}")

    # Connect and make requests
    await client.connect()

    await client.calculate(
        birth_date="1990-05-15",
        birth_time="14:30",
        timezone="UTC-05:00",
        latitude=40.7128,
        longitude=-74.0060
    )

    # Keep connection alive to receive response
    await asyncio.sleep(5)
    await client.disconnect()

asyncio.run(main())

Available Methods

MethodPermissionDescription
calculate()calculateCore temporal calculations
fetch_raw_sips()sips-readRaw SIPS coordinate data
fetch_raw_vortex()vortex-readRaw Vortex coordinate data
fetch_celestial_bodies()sips-readCelestial body coordinates (109 bodies)
get_celestial_bodies_list()-List all available celestial bodies
fetch_celestial_body_v2()sips-readCelestial Body v2 (sidereal-referenced)
get_celestial_body_v2_bodies_list()-List available bodies for Celestial Body v2 API
fetch_celestial_location()celestial-locationCelestial Map - Location & Distance
get_celestial_location_bodies_list()-List available bodies for Location API
get_celestial_location_health()-Health check for Location API
fetch_celestial_station()celestial-stationCelestial Map - Station & Shift
get_celestial_station_bodies_list()-List available bodies for Station API
get_celestial_station_health()-Health check for Station API

Async Context Manager

async with RetrogradeClient(api_key="your-key") as client:
    await client.calculate(...)
    # Auto-disconnects when exiting context

Lumina SDK AI/ML

Stream real-time Behavioral Modulation Signals (BMS) for AI/ML integration.

npm install @retrograde/lumina-sdk
# or
yarn add @retrograde/lumina-sdk
# or
pnpm add @retrograde/lumina-sdk

BMS Client (Processed Behavioral Signals)

import { BMSClient } from '@retrograde/lumina-sdk/bms';

const client = new BMSClient({
  apiKey: 'your-api-key',
  debug: true
});

// Listen for signals
client.on('signal', (data) => {
  const crimsonForge = data.signals['crimson-forge'];
  console.log(`Density: ${crimsonForge.density}`);
  console.log(`Brightness: ${crimsonForge.brightness}`);
});

// Connect and subscribe
await client.connect();
await client.subscribe({
  tier: 'standard',
  calendars: ['all'],
  interval: 5000
});

Constructor Options

interface ClientOptions {
  apiKey: string;           // Required: Your API key
  url?: string;             // WebSocket URL (defaults to production)
  autoReconnect?: boolean;  // Auto-reconnect on disconnect (default: true)
  maxReconnectAttempts?: number;  // Max reconnection attempts (default: 5)
  reconnectDelay?: number;  // Base delay between reconnects in ms (default: 1000)
  debug?: boolean;          // Enable debug logging (default: false)
}

Methods

MethodDescription
connect()Connect to WebSocket server
subscribe(config)Subscribe to stream
update(config)Update subscription configuration
unsubscribe()Stop receiving signals
disconnect()Close connection
on(event, callback)Register event listener
off(event, callback)Remove event listener
once(event, callback)One-time event listener
isConnected()Check connection status
isSubscribed()Check subscription status
getState()Get full connection state

Events

BMS Client Events
EventDescription
connectedFired when connected
subscribedFired when subscription confirmed
signalFired for each BMS signal
errorFired on errors
warningFired on warnings (e.g., rate limiting)
disconnectedFired on disconnect
reconnectingFired during reconnection attempts

Data Tiers

BMS Tiers
TierPropertiesBest For
minimal7Mobile apps, simple LLM prompts
standard22Most AI/ML applications
full35+Rich avatar systems, game NPCs
rawAllML training, research

Calendar IDs

const CALENDAR_IDS = [
  'monolith-stillness',  // Individuality
  'crimson-forge',       // Capacity
  'ember-serpent',       // Flexibility
  'solar-loom',          // Stability
  'emerald-grid',        // Context
  'tidal-compass',       // Continuity
  'indigo-exile',        // Content
  'twin-spiral',         // Duality
  'ouroboric-gate',      // Connectivity
];

LLM Integration Example

import { BMSClient } from '@retrograde/lumina-sdk/bms';
import OpenAI from 'openai';

const bms = new BMSClient({ apiKey: 'your-api-key' });
const openai = new OpenAI();

let currentPersonality = {};

bms.on('signal', (data) => {
  currentPersonality = data.signals;
});

await bms.connect();
await bms.subscribe({ tier: 'standard' });

async function chat(userMessage: string) {
  const crimson = currentPersonality['crimson-forge'] || {};

  // Map BMS to personality traits
  const tone = crimson.density > 1.1 ? 'energetic' :
               crimson.density < 0.9 ? 'calm' : 'balanced';

  const systemPrompt = `
    Current behavioral state:
    - Tone: ${tone}
    - Expressiveness: ${crimson.brightness > 0.7 ? 'high' : 'moderate'}
    - Stability: ${crimson.cohesiveness > 0.7 ? 'stable' : 'dynamic'}

    Adjust your responses to match this profile.
  `;

  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: userMessage }
    ]
  });

  return response.choices[0].message.content;
}

TypeScript Types

import type {
  BMSSignal,
  BMSSubscribeConfig,
  TemporalDataMessage,
  CalendarId,
  AspectName,
  HarmonyAnalysis,
  MaturityAnalysis,
} from '@retrograde/lumina-sdk';

Works in both Node.js and browsers. In browsers, uses native WebSocket. In Node.js, requires the ws package (included as dependency).

Python Lumina SDK AI/ML

Stream real-time Behavioral Modulation Signals (BMS) for AI/ML integration with Python async support.

pip install retrograde-lumina-sdk

BMS Client (Processed Behavioral Signals)

import asyncio
from retrograde_sdk import BMSClient

async def main():
    async with BMSClient(api_key="your-api-key", debug=True) as client:
        async for signal in client.stream(tier="standard", interval=5000):
            crimson = signal["crimson-forge"]
            print(f"Density: {crimson.density}")
            print(f"Brightness: {crimson.brightness}")
            print(f"Visibility: {crimson.visibility}")

asyncio.run(main())

BMSClient Options

from retrograde_sdk import BMSClient

client = BMSClient(
    api_key="your-api-key",
    url="wss://os.retrogradeobservatory.com/api/bms/v1/stream",  # default
    auto_reconnect=True,
    max_reconnect_attempts=5,
    reconnect_delay=1.0,
    debug=False
)

Methods & Properties

Methods
MethodDescription
await client.connect()Connect to WebSocket server
await client.subscribe(tier, calendars, interval)Subscribe to BMS stream
client.stream(...)Async iterator for BMS signals
await client.unsubscribe()Stop receiving signals
await client.disconnect()Close connection
Properties
PropertyDescription
client.is_connectedConnection status
client.is_subscribedSubscription status
client.connection_idCurrent connection ID

Callbacks

@client.on_signal
def handle_signal(signal: BMSSignal):
    print(signal.signals)

@client.on_error
def handle_error(code: str, message: str):
    print(f"Error {code}: {message}")

@client.on_warning
def handle_warning(code: str, message: str):
    print(f"Warning {code}: {message}")

Data Classes

BMSSignal
@dataclass
class BMSSignal:
    timestamp: str
    sequence: int
    tier: str
    signals: Dict[CalendarId, BMSSignalData]
    generation_time_ms: int
    next_push_ms: int
    calendar_count: int
BMSSignalData
@dataclass
class BMSSignalData:
    calendar_id: str
    aspect: str
    color_hex: str
    density: float
    brightness: float
    visibility: float
    rhythm_scale: float
    # ... additional properties based on tier
TemporalData
@dataclass
class TemporalData:
    timestamp: str
    sequence: int
    tier: str
    sips: Dict[CalendarId, SIPSData]
    vortex: Dict[CalendarId, VortexData]
    lumina_map: Dict[CalendarId, LuminaMapData]
    lumina_coordinate: Dict[AspectName, LuminaCoordinateData]
    harmony_analysis: Dict[CalendarId, HarmonyAnalysis]
    maturity_analysis: Dict[AspectName, MaturityAnalysis]
    fetch_time_ms: int
    next_push_ms: int
    data_source_status: DataSourceStatus

LLM Integration Example

import asyncio
from retrograde_sdk import BMSClient
from openai import OpenAI

client = OpenAI()
current_personality = {}

async def bms_listener():
    """Background task to update personality from BMS stream"""
    global current_personality

    async with BMSClient(api_key="your-key") as bms:
        async for signal in bms.stream(tier="standard", interval=5000):
            current_personality = signal.signals

def create_personality_context():
    """Convert BMS signals to LLM personality context"""
    crimson = current_personality.get("crimson-forge")
    if not crimson:
        return ""

    # Map BMS to personality traits
    if crimson.density > 1.1:
        tone = "energetic and enthusiastic"
    elif crimson.density < 0.9:
        tone = "calm and measured"
    else:
        tone = "balanced and steady"

    return f"""
    Current behavioral state:
    - Tone: {tone}
    - Expressiveness: {'high' if crimson.brightness > 0.7 else 'moderate'}
    - Stability: {'stable' if crimson.cohesiveness > 0.7 else 'dynamic'}
    - Response speed: {'quick' if crimson.responsiveness > 0.6 else 'thoughtful'}

    Adjust your responses to match this behavioral profile.
    """

def chat(user_message: str) -> str:
    """Chat using current BMS personality state"""
    context = create_personality_context()

    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": context},
            {"role": "user", "content": user_message}
        ]
    )

    return response.choices[0].message.content

Error Handling

from retrograde_sdk import BMSClient

async def main():
    client = BMSClient(api_key="your-key")

    @client.on_error
    def handle_error(code: str, message: str):
        if code == "RATE_LIMITED":
            print(f"Rate limited: {message}")
        elif code == "AUTH_FAILED":
            print(f"Authentication failed: {message}")
        else:
            print(f"Error {code}: {message}")

    @client.on_warning
    def handle_warning(code: str, message: str):
        if code == "RATE_THROTTLED":
            print(f"Throttled: {message}")

    try:
        await client.connect()
        await client.subscribe(tier="standard")
        async for signal in client.stream():
            process_signal(signal)
    except ConnectionError as e:
        print(f"Connection failed: {e}")
    finally:
        await client.disconnect()

Constants

Calendar IDs
from retrograde_sdk import CALENDAR_IDS

CALENDAR_IDS = [
    "monolith-stillness",  # Individuality
    "crimson-forge",       # Capacity
    "ember-serpent",       # Flexibility
    "solar-loom",          # Stability
    "emerald-grid",        # Context
    "tidal-compass",       # Continuity
    "indigo-exile",        # Content
    "twin-spiral",         # Duality
    "ouroboric-gate",      # Connectivity
]
Aspect Names
from retrograde_sdk import ASPECT_NAMES

ASPECT_NAMES = [
    "Individuality", "Capacity", "Flexibility",
    "Stability", "Context", "Content",
    "Continuity", "Duality", "Connectivity"
]

Requirements: Python >= 3.8, websockets >= 11.0, aiohttp >= 3.8

Contact Us

Get in touch with the Retrograde Observatory team