API Documentation

Getting Started

Authentication

All API requests require authentication using your API key. Include your key in the request header:

Authorization: Bearer YOUR_API_KEY

Get your API key from your account dashboard. API access requires a Professional tier subscription.

Base URL

https://api.astrovastum.com/v1

Rate Limits

• Professional Tier: 1,000 requests per hour
• Enterprise Tier: Custom limits

Endpoints

Generate Natal Chart

Calculate a complete natal chart with planetary positions, houses, and aspects.

Request

POST /charts/natal

Parameters

{
  "date": "1990-06-15",
  "time": "14:30:00",
  "timezone": "America/New_York",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "house_system": "placidus",
  "ayanamsa": "lahiri"
}

Response

{
  "chart_id": "ch_abc123xyz",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "3.0.1",
  "planets": [
    {
      "name": "Sun",
      "sign": "Gemini",
      "degree": 24.5623,
      "house": 10,
      "retrograde": false
    }
  ],
  "houses": [
    {
      "number": 1,
      "sign": "Virgo",
      "degree": 12.3456
    }
  ],
  "aspects": [
    {
      "planet1": "Sun",
      "planet2": "Moon",
      "type": "trine",
      "orb": 2.34,
      "applying": true
    }
  ],
  "confidence": 0.95,
  "systems_used": ["western", "vedic"]
}

Calculate Transits

Retrieve current planetary transits and their aspects to natal positions.

Request

GET /transits?chart_id=ch_abc123xyz&date=2025-01-15

Response

{
  "date": "2025-01-15",
  "transits": [
    {
      "planet": "Jupiter",
      "natal_planet": "Sun",
      "aspect": "conjunction",
      "orb": 1.23,
      "exact_date": "2025-01-16T08:45:00Z"
    }
  ],
  "confidence": 0.98
}

Get Progressions

Calculate secondary progressions for a specific date.

Request

POST /progressions

Parameters

{
  "chart_id": "ch_abc123xyz",
  "progression_date": "2025-01-15",
  "method": "secondary"
}

Vedic Chart Calculation

Generate Vedic (Jyotish) chart with divisional charts and dashas.

Request

POST /charts/vedic

Parameters

{
  "date": "1990-06-15",
  "time": "14:30:00",
  "timezone": "Asia/Kolkata",
  "latitude": 28.6139,
  "longitude": 77.2090,
  "ayanamsa": "lahiri",
  "divisional_charts": ["d9", "d10"]
}

Error Handling

The API uses standard HTTP status codes:

• 200: Success
• 400: Bad Request - Invalid parameters
• 401: Unauthorized - Invalid API key
• 429: Rate limit exceeded
• 500: Server error

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid date format",
    "field": "date"
  }
}

Webhooks

Configure webhooks to receive notifications for:

• Chart calculation completion
• Transit alerts
• API usage thresholds

Configure webhooks in your account settings.

SDKs and Libraries

Official SDKs available for:

• JavaScript/Node.js
• Python
• PHP
• Ruby

View installation instructions and examples on our GitHub.

Support

For API support:

• Email: api-support@astrovastum.com
• Documentation: Support Center
• Status Page: status.astrovastum.com