Documentation
Build with REST APIs, WebSockets, and SDKs
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 |
|---|---|---|---|
7F7F7F | monolith-stillness | Individuality | Baseline identity |
FF0000 | crimson-forge | Capacity | Effort readiness |
FF4000 | ember-serpent | Flexibility | Adaptation |
FFFF00 | solar-loom | Stability | Consistency |
00FF00 | emerald-grid | Context | Perception |
00FFC0 | tidal-compass | Continuity | Durability |
0000FF | indigo-exile | Content | Introspection |
FF00FF | twin-spiral | Duality | Polarity |
606F | ouroboric-gate | Connectivity | Integration |
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 |
|---|---|
| Demo | 10 requests per 15 minutes |
| Standard | 50 requests per 15 minutes |
| Premium | 100 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
| Parameter | Type | Required | Description |
|---|---|---|---|
birthDate | string | Yes | Birth date (YYYY-MM-DD) |
birthTime | string | Yes | Birth time (HH:MM:SS, 24-hour) |
latitude | number | Yes | Location latitude (-90 to 90) |
longitude | number | Yes | Location longitude (-180 to 180) |
timezone | string | Recommended | Timezone 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
/signal
Get BMS signal for current or specified calendar
/signals
Get BMS signals for all 9 calendars
/signal
Generate BMS signal for specific date/time/location
Tier System
| Tier | Properties | Rate Limit | Best For |
|---|---|---|---|
minimal | ~7 | 100 req/min | Mobile apps, widgets |
standard | ~22 | 60 req/min | Most applications |
full | ~35+ | 30 req/min | Rich visualizations |
raw | All | 10 req/min | Research, 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.
/
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
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Must be "fetchAndStoreAllCalendarData" |
system.startDate | string | Yes | Birth date in YYYY-MM-DD format |
system.startTime | string | Yes | Birth time in HH:MM format |
system.timezone | string | Yes | UTC offset (e.g., "UTC+5:30", "UTC-5") |
system.latitude | number | Yes | Latitude (-90 to 90) |
system.longitude | number | Yes | Longitude (-180 to 180) |
calendars | array | Yes | Array 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
| Field | Type | Description |
|---|---|---|
Calendar | string | Calendar code identifier |
scale_X | number | X coordinate |
scale_Y | number | Y coordinate |
scale_Z | number | Z coordinate |
radial_Location | number | Spherical rho (distance from origin) |
polar_Angle | number | Spherical theta (polar angle in degrees) |
azimuthal_Angle | number | Spherical phi (azimuthal angle in degrees) |
sphericalCoord_area | number | Surface area of sphere with radius rho |
sphericalCoord_volume | number | Volume of sphere with radius rho |
sphericalCoord_Distance | number | Time spread (distance between positions) |
sphericalCoord_Angular | number | Time curve (angular separation) |
/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
}
/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.
/
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
| Field | Type | Description |
|---|---|---|
Calendar | string | Calendar code identifier |
scale_X | number | X coordinate - mapped as 'span' |
scale_Z | number | Z coordinate - mapped as 'orbit' |
scale_Y | number | Y coordinate - mapped as 'era' |
radial_Location | number | Spherical rho (distance from origin) |
polar_Angle | number | Spherical theta (polar angle in degrees) |
azimuthal_Angle | number | Spherical phi (azimuthal angle in degrees) |
sphericalCoord_Area | number | Surface area of sphere with radius rho |
sphericalCoord_Volume | number | Volume of sphere with radius rho |
sphericalCoord_Distance | number | Time spread (distance between positions) |
sphericalCoord_Angle | number | Time curve (angular separation) |
/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
}
/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.
/
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
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Must be "fetchAndStoreAllCalendarData" |
system.startDate | string | Yes | Birth date in YYYY-MM-DD format |
system.startTime | string | Yes | Birth time in HH:MM format |
system.timezone | string | Yes | UTC offset (e.g., "+05:30", "-05:00") |
system.latitude | number | Yes | Observer latitude (-90 to 90) |
system.longitude | number | Yes | Observer longitude (-180 to 180) |
system.endDate | string | No | Present date (defaults to now) |
system.endTime | string | No | Present time (defaults to now) |
celestialBodies | array | Yes | Array 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
| Field | Type | Description |
|---|---|---|
celestialBody | string | Display name of the celestial body |
bodyType | string | Type: star, planet, satellite, dwarf_planet, asteroid, comet, centaur, tno, lagrange |
scale_X | number | X coordinate |
scale_Y | number | Y coordinate |
scale_Z | number | Z coordinate |
radial_Location | number | Spherical rho (distance from origin) |
polar_Angle | number | Spherical theta (polar angle in degrees) |
azimuthal_Angle | number | Spherical phi (azimuthal angle in degrees) |
sphericalCoord_area | number | Surface area of sphere with radius rho |
sphericalCoord_volume | number | Volume of sphere with radius rho |
sphericalCoord_Distance | number | Spherical distance between birth and present positions |
sphericalCoord_Angular | number | Angular separation between birth and present |
/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" }
]
}
}
/health
Health check endpoint. No authentication required.
Additional Endpoints: GET /docs, GET /status, GET /version
Available Celestial Bodies
| Type | Bodies |
|---|---|
| Planets | Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune |
| Dwarf Planets | Pluto, Ceres, Eris, Makemake, Haumea |
| Satellites | Moon, Io, Europa, Ganymede, Callisto, Titan, Enceladus, Mimas, Tethys, Dione, Rhea, Iapetus, Miranda, Ariel, Umbriel, Titania, Oberon, Triton, Charon |
| Asteroids | Vesta, Pallas, Hygiea, Juno |
| Comets | Halley, Encke, Tempel 1 |
| Centaurs | Chiron, Pholus, Nessus |
| TNOs | Sedna, Quaoar, Orcus, Varuna, Ixion |
| Stars | Sirius, 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
/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, outputstemporal_location(Location) &temporal_distance(Distance) - Celestial Station API (
/api/celestialstation/v1) - Temporal Station based on Macro Timestamp, outputstemporal_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
/
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
| Field | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | Birth/start date (YYYY-MM-DD) |
startTime | string | Yes | Birth/start time (HH:MM) |
timezone | string | Yes | UTC offset (e.g., UTC-5, UTC+5:30) |
latitude | number | Yes | Observer latitude (-90 to 90) |
longitude | number | Yes | Observer longitude (-180 to 180) |
celestialBodies | array | Yes | Array of celestial body IDs |
endDate | string | No | Present date (defaults to now) |
endTime | string | No | Present time (defaults to now) |
format | string | No | Response 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
| Field | Type | Description |
|---|---|---|
temporal_location | number | Location - Present coordinate value (rho) in 3D space |
temporal_distance | number | Distance - Spherical distance from birth to present coordinates |
spherical_coordinates | object | Full spherical coordinates (rho, theta, phi) |
inter_body_distances | object | Distances between this body and other requested bodies |
Celestial Station API v1
Base URL: /api/celestialstation/v1
/
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
| Field | Type | Description |
|---|---|---|
temporal_station | number | Station - Present coordinate value (rho) in 3D space |
temporal_shift | number | Shift - Spherical distance from birth to present coordinates |
elapsedNodes | number | Total elapsed time nodes |
presentNode | number | Current time node |
interBodyShift | object | Shifts between this body and other requested bodies |
Public Endpoints (No Auth Required)
| Endpoint | Description |
|---|---|
GET /api/celestiallocation/v1/bodies | List all 114 available celestial bodies |
GET /api/celestiallocation/v1/health | API health check |
GET /api/celestiallocation/v1/docs | API documentation |
GET /api/celestialstation/v1/bodies | List all 114 available celestial bodies |
GET /api/celestialstation/v1/health | API health check |
GET /api/celestialstation/v1/docs | API documentation |
Supported Celestial Bodies (114 Total)
| Category | Count | Examples |
|---|---|---|
| Planets | 7 | mercury, venus, mars, jupiter, saturn, uranus, neptune |
| Dwarf Planets | 5 | pluto, ceres, eris, makemake, haumea |
| Major Satellites | 9 | moon, io, europa, ganymede, callisto, titan, triton |
| Asteroids & Centaurs | 7 | vesta, pallas, chiron, pholus, nessus |
| Trans-Neptunian Objects | 5 | sedna, quaoar, orcus, varuna, ixion |
| Comets | 3 | halley, encke, tempel1 |
| Stars | 63 | sirius, 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
| Handler | Request Event | Response Events | Permission |
|---|---|---|---|
| Calculate | calculate:request | calculate:response, calculate:error | calculate |
| Raw SIPS | rawsips:request | rawsips:response, rawsips:error | sips-read |
| Raw Vortex | rawvortex:request | rawvortex:response, rawvortex:error | vortex-read |
| Celestial Body | celestial:request | celestial:response, celestial:error | sips-read |
| Celestial Body (v2) | celestial:v2:request | celestial:v2:response, celestial:v2:error | sips-read |
| Celestial Location | celestiallocation:request | celestiallocation:response, celestiallocation:error | celestial-location |
| Celestial Station | celestialstation:request | celestialstation:response, celestialstation:error | celestial-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 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
| Field | Description |
|---|---|
scale_X | X coordinate |
scale_Y | Y coordinate |
scale_Z | Z coordinate |
radial_Location | Spherical rho (distance from origin) |
polar_Angle | Spherical theta (degrees) |
azimuthal_Angle | Spherical phi (degrees) |
sphericalCoord_area | Surface area of sphere |
sphericalCoord_volume | Volume of sphere |
sphericalCoord_Distance | Time spread |
sphericalCoord_Angular | Time curve |
rawvortex:request 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
| Field | Description |
|---|---|
scale_X | X coordinate - span |
scale_Z | Z coordinate - orbit |
scale_Y | Y coordinate - era |
radial_Location | Spherical rho (distance from origin) |
polar_Angle | Spherical theta (degrees) |
azimuthal_Angle | Spherical phi (degrees) |
sphericalCoord_Area | Surface area of sphere |
sphericalCoord_Volume | Volume of sphere |
sphericalCoord_Distance | Time spread |
sphericalCoord_Angle | Time curve |
celestial:request 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
| Field | Description |
|---|---|
celestialBody | Display name of the celestial body |
bodyType | Type: star, planet, satellite, dwarf_planet, asteroid, comet, centaur, tno, lagrange |
scale_X | X coordinate |
scale_Y | Y coordinate |
scale_Z | Z coordinate |
radial_Location | Spherical rho (distance from origin) |
polar_Angle | Spherical theta (degrees) |
azimuthal_Angle | Spherical phi (degrees) |
sphericalCoord_area | Surface area of sphere |
sphericalCoord_volume | Volume of sphere |
sphericalCoord_Distance | Spherical distance between birth and present |
sphericalCoord_Angular | Angular 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 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
| Field | Description |
|---|---|
celestialBody | Display name of the celestial body |
bodyType | Type: star, planet, satellite, dwarf_planet, asteroid, comet, centaur, tno, lagrange |
scale_X | X coordinate |
scale_Y | Y coordinate |
scale_Z | Z coordinate |
radial_Location | Spherical rho (distance from origin) |
polar_Angle | Spherical theta (degrees) |
azimuthal_Angle | Spherical phi (degrees) |
sphericalCoord_area | Surface area of sphere |
sphericalCoord_volume | Volume of sphere |
sphericalCoord_Distance | Spherical distance between birth and present |
sphericalCoord_Angular | Angular 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-locationpermission) - celestialstation:* - Station & Shift (requires
celestial-stationpermission)
celestiallocation:request
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
| Field | Description |
|---|---|
temporal_location | Location - Present coordinate value (rho) in 3D space |
temporal_distance | Distance - Spherical distance from birth to present coordinates |
spherical_coordinates | Full spherical coordinates (rho, theta, phi) |
inter_body_distances | Distances 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
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
| Field | Description |
|---|---|
temporal_station | Station - Present coordinate value (rho) in 3D space |
temporal_shift | Shift - Spherical distance from birth to present coordinates |
elapsedNodes | Total elapsed time nodes |
presentNode | Current time node |
interBodyShift | Shifts 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 Event | Response Events | Permission |
|---|---|---|
celestiallocation:request | celestiallocation:response, celestiallocation:error | celestial-location |
celestiallocation:bodies | celestiallocation:bodies:response | - |
celestiallocation:health | celestiallocation:health:response | - |
celestialstation:request | celestialstation:response, celestialstation:error | celestial-station |
celestialstation:bodies | celestialstation:bodies:response | - |
celestialstation:health | celestialstation: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
- Client connects to WebSocket endpoint
- Server sends
connectedmessage with available options - Client sends
subscribemessage with API key and config - Server sends
subscribedconfirmation - Server pushes
bmsmessages at configured interval - Client can send
updateto change config orunsubscribeto 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
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Must be "subscribe" |
apiKey | string | Yes | Your API key |
config.tier | string | No | "minimal", "standard", "full", "raw" (default: "standard") |
config.calendars | string[] | No | Calendar IDs or ["all"] (default: all 9 calendars) |
config.interval | number | No | Push interval in ms: 1000, 5000, 10000 (default: 5000) |
config.params | object | No | Custom 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
| Tier | Properties | Messages/Min | Min Interval | Best For |
|---|---|---|---|---|
minimal | 7 | 120 | 1000ms | Mobile apps, simple LLM prompts |
standard | 22 | 60 | 5000ms | Most AI/ML applications |
full | 35+ | 30 | 5000ms | Rich avatar systems, game NPCs |
raw | All | 12 | 10000ms | ML 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
| Code | Description |
|---|---|
AUTH_FAILED | Invalid or missing API key |
INVALID_MESSAGE | Malformed JSON or unknown message type |
INVALID_CONFIG | Invalid subscription configuration |
RATE_LIMITED | Rate limit exceeded |
RATE_THROTTLED | Temporarily throttled (warning) |
MAX_CONNECTIONS | Server connection limit reached |
MAX_CONNECTIONS_PER_IP | Per-IP connection limit reached (max 10) |
SIGNAL_ERROR | Failed 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
| Method | Permission | Description |
|---|---|---|
calculate() | calculate | Core temporal calculations |
fetchRawSIPS() | sips-read | Raw SIPS coordinate data |
fetchRawVortex() | vortex-read | Raw Vortex coordinate data |
fetchCelestialBodies() | sips-read | Celestial body coordinates (109 bodies) |
getCelestialBodiesList() | - | List all available celestial bodies |
fetchCelestialBodyV2() | sips-read | Celestial Body v2 (sidereal-referenced) |
getCelestialBodyV2BodiesList() | - | List available bodies for Celestial Body v2 API |
fetchCelestialLocation() | celestial-location | Celestial Map - Location & Distance |
getCelestialLocationBodiesList() | - | List available bodies for Location API |
getCelestialLocationHealth() | - | Health check for Location API |
fetchCelestialStation() | celestial-station | Celestial Map - Station & Shift |
getCelestialStationBodiesList() | - | List available bodies for Station API |
getCelestialStationHealth() | - | Health check for Station API |
Connection Methods
| Method | Description |
|---|---|
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
| Method | Permission | Description |
|---|---|---|
calculate() | calculate | Core temporal calculations |
fetch_raw_sips() | sips-read | Raw SIPS coordinate data |
fetch_raw_vortex() | vortex-read | Raw Vortex coordinate data |
fetch_celestial_bodies() | sips-read | Celestial body coordinates (109 bodies) |
get_celestial_bodies_list() | - | List all available celestial bodies |
fetch_celestial_body_v2() | sips-read | Celestial Body v2 (sidereal-referenced) |
get_celestial_body_v2_bodies_list() | - | List available bodies for Celestial Body v2 API |
fetch_celestial_location() | celestial-location | Celestial 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-station | Celestial 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
| Method | Description |
|---|---|
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
| Event | Description |
|---|---|
connected | Fired when connected |
subscribed | Fired when subscription confirmed |
signal | Fired for each BMS signal |
error | Fired on errors |
warning | Fired on warnings (e.g., rate limiting) |
disconnected | Fired on disconnect |
reconnecting | Fired during reconnection attempts |
Data Tiers
BMS Tiers
| Tier | Properties | Best For |
|---|---|---|
minimal | 7 | Mobile apps, simple LLM prompts |
standard | 22 | Most AI/ML applications |
full | 35+ | Rich avatar systems, game NPCs |
raw | All | ML 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
| Method | Description |
|---|---|
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
| Property | Description |
|---|---|
client.is_connected | Connection status |
client.is_subscribed | Subscription status |
client.connection_id | Current 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