🔮 AstroWisdoms Chart API

📚 API Overview

Welcome to the AstroWisdoms Astrology Chart API documentation. Our API enables you to generate detailed Vedic astrology birth charts including planetary positions, nakshatras, dashas, and visual SVG chart representations.

🔐 Authentication

All API requests require authentication using a Bearer token. Include your API token in the request header as follows:

🌐 API Endpoint

Send a POST request to this endpoint with birth details in JSON format to generate an astrological chart.

📋 Request Format

Option 1: Using Well-Known Place Name

If the birth location is a well-known city or place, the API will automatically determine the geographical coordinates and timezone:

Option 2: Using Manual Coordinates

For precise locations or if the place name is not recognized by the API, provide latitude, longitude, and timezone manually:

Request Parameters

Note: You must provide EITHER the place parameter OR all three parameters (lat, log, timezone).

✅ Response Structure

The API returns a comprehensive JSON response containing all astrological calculations and chart visualizations:

Main Response Components

• success (Boolean) - Indicates whether the request was successful
• message (String) - Descriptive status message
• charts (Object) - Contains two SVG chart representations:
  • main_chart - Traditional North Indian diamond-shaped chart
  • circle_chart - Simplified rectangular format chart
• astrological_data (Object) - Complete planetary calculations including:
  • Ascendant (Lagna) details with degree, nakshatra, and pada
  • Moon position with rashi, nakshatra, and house placement
  • All planetary positions with detailed nakshatra information
  • Complete Mahadasha and Antardasha periods with dates
  • KP System Star Lords and Sub-Lords
• birth_info (Object) - Confirmed birth details used for calculations
• user_info (Object) - User account information
• generated_at (String) - ISO timestamp of chart generation

Chart Data Format

Each chart object contains:

• svg_base64 - Base64 encoded SVG string (ready to decode and display)
• filepath - Server file path (for reference)
• type - Chart type description
• description - Chart purpose and content description

Displaying SVG Charts

To display the charts in your application, decode the Base64 string:

// JavaScript example
const svgData = response.charts.main_chart.svg_base64;
const decodedSVG = atob(svgData);
document.getElementById('chart-container').innerHTML = decodedSVG;

// Or create an image element
const img = new Image();
img.src = 'data:image/svg+xml;base64,' + svgData;
document.body.appendChild(img);

💡 Implementation Examples

JavaScript (Fetch API)

const generateAstroChart = async () => {
  try {
    const response = await fetch('https://astrowisdoms.com/api/chart', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN'
      },
      body: JSON.stringify({
        birth: {
          name: "Rahul Kumar",
          date: "1990-05-15",
          time: "10:30",
          place: "Mumbai, Maharashtra, India"
        }
      })
    });
    
    const data = await response.json();
    
    if (data.success) {
      // Display main chart
      const mainChartSVG = atob(data.charts.main_chart.svg_base64);
      document.getElementById('main-chart').innerHTML = mainChartSVG;
      
      // Access planetary data
      console.log('Ascendant:', data.astrological_data.ascendant);
      console.log('Moon Sign:', data.astrological_data.moon_details.rashi);
    }
  } catch (error) {
    console.error('Error generating chart:', error);
  }
};

Python (Requests Library)

  import requests
import json
import base64

url = "https://astrowisdoms.com/api/chart"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_TOKEN"
}

payload = {
    "birth": {
        "name": "Priya Sharma",
        "date": "1992-08-20",
        "time": "14:45",
        "place": "Karnal, Haryana, India"
    }
}

try:
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    
    data = response.json()
    
    if data['success']:
        # Decode and save SVG chart
        svg_data = data['charts']['main_chart']['svg_base64']
        svg_decoded = base64.b64decode(svg_data)
        
        with open('birth_chart.svg', 'wb') as f:
            f.write(svg_decoded)
        
        # Print astrological data
        print(f"Ascendant: {data['astrological_data']['ascendant']['rashi']}")
        print(f"Moon Sign: {data['astrological_data']['moon_details']['rashi']}")
        
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

cURL Command

curl -X POST https://astrowisdoms.com/api/chart \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "birth": {
      "name": "Amit Patel",
      "date": "1988-12-10",
      "time": "06:15",
      "place": "Ahmedabad, Gujarat, India"
    }
  }'

PHP Example

<?php

$url = "https://astrowisdoms.com/api/chart";
$token = "YOUR_API_TOKEN";

$data = array(
    "birth" => array(
        "name" => "Vikram Singh",
        "date" => "1995-03-25",
        "time" => "08:00",
        "place" => "Jaipur, Rajasthan, India"
    )
);

$options = array(
    'http' => array(
        'header'  => "Content-Type: application/json\r\n" .
                      "Authorization: Bearer " . $token . "\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

if ($result !== FALSE) {
    $response = json_decode($result, true);
    echo "Chart generated successfully!\n";
    echo "Ascendant: " . $response['astrological_data']['ascendant']['rashi'];
}

?>

⚠️ Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Error Response Format

When an error occurs, the API returns a JSON response with error details:

Common Error Scenarios

• Invalid Date Format: Ensure date is in YYYY-MM-DD format (e.g., "1990-05-15")
• Invalid Time Format: Use 24-hour HH:MM format (e.g., "14:30" not "2:30 PM")
• Place Not Found: Use Option 2 with manual coordinates if place is not recognized
• Missing Coordinates: When using Option 2, all three (lat, log, timezone) must be provided
• Invalid Timezone: Use valid IANA timezone identifiers (e.g., "Asia/Kolkata")

📝 Best Practices

Input Validation

• Always validate birth date and time formats on the client-side before sending requests
• Ensure dates are realistic (not in the future, not before 1900)
• Verify time is in 24-hour format (00:00 to 23:59)
• Trim whitespace from input fields

Location Handling

• For well-known cities, use Option 1 (place name) for simplicity
• For villages or precise locations, use Option 2 with exact coordinates
• Store latitude, longitude, and timezone with chart data for future reference
• Use standard timezone identifiers from the IANA Time Zone Database

Performance Optimization

• Cache generated charts to minimize API calls for the same birth data
• Store SVG charts in your database or file system after first generation
• Implement request throttling on your client to respect rate limits
• Use asynchronous requests to avoid blocking your application

Security Considerations

• Never expose your API token in client-side JavaScript code
• Make API calls from your backend server, not from the browser
• Store tokens securely using environment variables
• Rotate API tokens periodically for enhanced security
• Use HTTPS for all API communications

Data Storage

• Store the complete API response for comprehensive record-keeping
• Save both SVG charts separately for quick access
• Index charts by user ID and timestamp for efficient retrieval
• Consider storing planetary positions for quick comparisons

📊 Understanding Response Data

Planetary Positions

Each planet in the response includes:

• longitude_sidereal: Sidereal longitude in degrees (0-360°)
• rashi: Zodiac sign name (e.g., "Scorpio", "Pisces")
• rashi_index: Sign number (1-12)
• degree_in_rashi: Position within the sign (0-30°)
• nakshatra: Birth star name (e.g., "Jyeshtha", "Uttara Bhadrapada")
• nakshatra_pada: Quarter division (1-4)
• nakshatra_lord: Ruling planet of the nakshatra
• house: House placement (1-12)
• retrograde: Retrograde status (0 = direct, 1 = retrograde)

Mahadasha Periods

The Vimshottari Dasha system provides:

• lord: Ruling planet for the period
• start_iso_utc: Period start date in ISO 8601 format
• end_iso_utc: Period end date in ISO 8601 format
• duration_years: Total duration in years
• antardashas: Array of sub-periods with same structure

Ascendant Details

The Lagna (Ascendant) information includes:

• degree_in_rashi: Exact degree position in the rising sign
• nakshatra: Nakshatra at the time of birth
• pada: Pada (quarter) of the nakshatra
• rashi: Rising sign (Lagna)

KP System Data

Krishnamurti Paddhati (KP) system includes:

• Star_Lord: Nakshatra lord for the cusp
• Sub_Lord: Sub-division lord (critical for predictions)
• Percent_in_Nakshatra: Percentage position within the nakshatra

🌏 Timezone Reference

Common Indian timezones for use with the API:

For other regions, refer to the IANA Time Zone Database.

⏱️ Rate Limits

To ensure fair usage and optimal performance for all users, the API implements rate limiting:

Rate limit information is included in response headers:

🆘 Support & Resources

Get Help

• 📧 Email Support: mohitraj.cs@gmail.com
• 📖 Full Documentation: https://astrowisdoms.com/docs
• 🐛 Report Issues: https://astrowisdoms.com/issues