Birth Chart API

Generate complete Vedic birth charts (Kundli)

POST /v2/astrology/birth-chart $0.020/call

Basic Usage

import { VedikaClient } from '@vedika-io/sdk';

const client = new VedikaClient({ apiKey: process.env.VEDIKA_API_KEY });

const chart = await client.post('/v2/astrology/birth-chart', {
  datetime: '1990-05-15T10:30:00',
  latitude: 28.6139,
  longitude: 77.2090,
  timezone: '+05:30'
});

console.log(chart.sunSign);         // e.g. 'Taurus'
console.log(chart.moonSign);        // e.g. 'Sagittarius'
console.log(chart.ascendant.sign);  // rising sign, e.g. 'Cancer'
console.log(chart.nakshatra);       // birth nakshatra, e.g. 'Uttara Ashadha'

Parameters

Parameter Type Required Description
datetime string Yes ISO 8601 datetime with timezone offset
latitude number Yes Birth location latitude (-90 to 90)
longitude number Yes Birth location longitude (-180 to 180)
timezone string No IANA timezone (e.g., 'Asia/Kolkata')
ayanamsa string No 'lahiri' (default), 'krishnamurti', 'raman'
houseSystem string No 'placidus' (default), 'whole-sign', 'equal'

Response Structure

// What client.post() returns: the "data" object of the API response.
// The SDK removes the { success, data } wrapper; billing is on chart.__envelope.
// Raw HTTP callers read the same fields under body.data and billing under body.billing.
{
  "sunSign": "Taurus",
  "moonSign": "Sagittarius",
  "nakshatra": "Uttara Ashadha",
  "tithi": "Krishna Panchami",

  "ascendant": {
    "sign": "Cancer",
    "signLord": "Moon",
    "degree": 9.89,
    "nakshatra": { "name": "Pushya", "pada": 2, "lord": "Saturn", "deity": "Brihaspati" }
  },

  "planets": [
    {
      "name": "Sun",
      "sign": "Taurus",
      "signLord": "Venus",
      "house": 11,
      "degree": 0.4,
      "nakshatra": { "name": "Krittika", "pada": 2, "lord": "Sun", "deity": "Agni" },
      "isRetrograde": false
    }
    // ... Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu
  ],

  "houses": [
    { "number": 1, "sign": "Cancer", "signLord": "Moon", "lord": "Moon", "cusp": 90 }
    // ... houses 2-12
  ],

  "ayanamsa": { "id": 1, "name": "Lahiri", "value": 23.718659 },

  // SVG renderings of the chart (north and south Indian styles)
  "chart": { "format": "svg", "northIndian": "<svg ...>", "southIndian": "<svg ...>" }
}

Advanced Options

// With an explicit ayanamsa
const chart = await client.post('/v2/astrology/birth-chart', {
  datetime: '1990-05-15T10:30:00',
  latitude: 28.6139,
  longitude: 77.2090,
  timezone: '+05:30',
  ayanamsa: 'lahiri'            // Ayanamsa system
});

Divisional Charts (Vargas)

Get divisional charts like D9 (Navamsha), D10 (Dashamsha):

const birthDetails = {
  datetime: '1990-05-15T10:30:00',
  latitude: 28.6139,
  longitude: 77.2090,
  timezone: '+05:30'
};

// Get Navamsha chart (D9)
const navamsha = await client.getDivisionalChart('navamsa', birthDetails);

// Get Dashamsha chart (D10) for career
const dashamsha = await client.getDivisionalChart('dashamsa', birthDetails);

// Any supported division by number (D7 here)
const saptamsha = await client.post('/v2/astrology/divisional-chart', {
  ...birthDetails,
  division: 7
});

console.log(navamsha);

// Supported divisions: 1, 2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45, 60
// Common: D9 (marriage), D10 (career), D7 (children), D4 (property)

TypeScript Types

import { VedikaClient } from '@vedika-io/sdk';

// The fields this page reads from POST /v2/astrology/birth-chart
interface ChartPlanet {
  name: string;
  sign: string;
  signLord: string;
  house: number;
  degree: number;
  nakshatra: { name: string; pada: number };
  isRetrograde: boolean;
}

interface ChartHouse {
  number: number;
  sign: string;
  signLord: string;
}

interface BirthChartPayload {
  sunSign: string;
  moonSign: string;
  nakshatra: string;
  ascendant: { sign: string; degree: number };
  planets: ChartPlanet[];
  houses: ChartHouse[];
}

const client = new VedikaClient({ apiKey: process.env.VEDIKA_API_KEY! });

const chart = await client.post<BirthChartPayload>('/v2/astrology/birth-chart', {
  datetime: '1990-05-15T10:30:00',
  latitude: 28.6139,
  longitude: 77.2090,
  timezone: '+05:30'
});

// Access typed properties
const sun = chart.planets.find(p => p.name === 'Sun')!;
console.log(sun.sign);  // e.g. 'Taurus'

const firstHouse: ChartHouse = chart.houses[0];
console.log(firstHouse.signLord);  // e.g. 'Moon'

Real-World Example

// Complete birth chart analysis
async function analyzeBirthChart(birthDetails) {
  const client = new VedikaClient({ apiKey: process.env.VEDIKA_API_KEY });

  // Get main birth chart
  const chart = await client.post('/v2/astrology/birth-chart', birthDetails);

  // Build analysis object
  const analysis = {
    // Basic signs
    personality: {
      sunSign: chart.sunSign,
      moonSign: chart.moonSign,
      risingSign: chart.ascendant.sign
    },

    // Birth nakshatra
    nakshatra: chart.nakshatra,

    // Planet positions by house
    planetsByHouse: chart.planets.reduce((acc, planet) => {
      acc[planet.house] = acc[planet.house] || [];
      acc[planet.house].push(planet.name);
      return acc;
    }, {}),

    // Planets in the 1st or 10th house
    prominentPlanets: chart.planets.filter(p =>
      p.house === 1 || p.house === 10
    ).map(p => p.name),

    // Retrograde planets
    retrogradePlanets: chart.planets.filter(p =>
      p.isRetrograde
    ).map(p => p.name)
  };

  return analysis;
}

// Usage
const result = await analyzeBirthChart({
  datetime: '1990-05-15T10:30:00',
  latitude: 28.6139,
  longitude: 77.2090,
  timezone: '+05:30'
});

console.log('Analysis:', result);

Related APIs