Astrology API Node.js SDK (DivineAPI)

Verified live against the DivineAPI API on 2 October 2026.

Official DivineAPI JavaScript and TypeScript client for Vedic, Western, horoscope, tarot and numerology astrology endpoints. It has typed parameters and returns the API's JSON.

Get your API key

Start the 14-day free trial (credit card required to activate the trial).
Copy your API key and auth token from the DivineAPI dashboard. The SDK sends the token as an Authorization: Bearer header and the key as the api_key form field on every request.

Requirements

Node.js 18+ (uses native fetch)
Zero external dependencies

Installation

npm install divineapi

Quick Start

ES module (save as index.mjs, run with node index.mjs):

import { DivineApi } from 'divineapi';

const client = new DivineApi({ apiKey: 'YOUR_API_KEY', authToken: 'YOUR_AUTH_TOKEN' });

// Western natal chart: planets for a birth in New York (tzone -4 = EDT on that date)
const res = await client.western.natal.planetaryPositions({
  full_name: 'Jane Smith', gender: 'female',
  day: 15, month: 6, year: 1995, hour: 8, min: 0, sec: 0,
  place: 'new york', lat: 40.7128, lon: -74.006, tzone: -4,
  house_system: 'placidus',
});

console.log(res.status);                               // 'success'
for (const p of res.data.slice(0, 4)) console.log(p.name, p.sign, p.longitude, 'house', p.house);
// Ascendant Cancer 26:25:42 house 1
// Sun Gemini 23:55:56 house 11
// Moon Capricorn 26:59:57 house 7
// Mars Virgo 10:6:0 house 3

CommonJS works too: const { DivineApi } = require('divineapi');

Real response (2 Oct 2026, trimmed with ...). Since 1.10.0 this method uses astroapi-8, so the envelope is status, not success:

{
  "status": "success",
  "code": 200,
  "message": "Request successful",
  "data": [
    {
      "name": "Ascendant",
      "full_degree": "116.4283411",
      "sign": "Cancer",
      "sign_no": 4,
      "longitude": "26:25:42",
      "house": 1,
      "element": "Water",
      "modality": "Cardinal",
      "...": "..."
    },
    {
      "name": "Sun",
      "full_degree": "83.9322195",
      "sign": "Gemini",
      "longitude": "23:55:56",
      "is_retro": "false",
      "house": 11,
      "...": "..."
    },
    {
      "name": "Moon",
      "full_degree": "296.9992259",
      "sign": "Capricorn",
      "longitude": "26:59:57",
      "is_setting": "true",
      "house": 7,
      "...": "..."
    },
    "..."
  ]
}

Configuration

const client = new DivineApi({
  apiKey: 'YOUR_API_KEY',       // Required: API key from the dashboard
  authToken: 'YOUR_AUTH_TOKEN', // Use the auth token from the dashboard (if omitted, the SDK sends apiKey as the Bearer token)
  timeout: 60000,               // Optional (default: 30000ms)
});

API Categories

Horoscope & Tarot

client.horoscope.daily(params)    // params.h_day: 'today' | 'tomorrow' | 'yesterday'
client.horoscope.weekly(params)   // params.week:  'current' | 'prev' | 'next'
client.horoscope.monthly(params)  // params.month: 'current' | 'prev' | 'next'
client.horoscope.yearly(params)   // params.year:  'current' | 'prev' | 'next'
client.horoscope.chinese(params)
client.horoscope.numerology(params)
client.horoscope.yesOrNoTarot(params)
client.horoscope.dailyTarot(params)
client.horoscope.fortuneCookie(params)
client.horoscope.coffeeCupReading(params)
client.horoscope.careerDailyReading(params)
client.horoscope.divineAngelReading(params)        // Divine Angel Reading: an angel-card reading with a short message of encouragement
client.horoscope.divineMagicReading(params)
client.horoscope.dreamComeTrueReading(params)      // Dream Come True Reading: 1 to 5 tarot cards about a wish (love, hopes, goals)
client.horoscope.egyptianPrediction(params)
client.horoscope.eroticLoveReading(params)
client.horoscope.exFlameReading(params)
client.horoscope.flirtLoveReading(params)
client.horoscope.heartbreakReading(params)
client.horoscope.inDepthLoveReading(params)
client.horoscope.knowYourFriendReading(params)
client.horoscope.loveCompatibility(params)
client.horoscope.loveTriangleReading(params)
client.horoscope.madeForEachOther(params)
client.horoscope.powerLifeReading(params)
client.horoscope.pastLivesConnectionReading(params)
client.horoscope.pastPresentFutureReading(params)
client.horoscope.whichAnimalAreYou(params)
client.horoscope.wisdomReading(params)

Indian Astrology - Panchang

client.indian.panchang.findPanchang(params)
client.indian.panchang.findSunAndMoon(params)
client.indian.panchang.findChandramasa(params)
client.indian.panchang.findSamvat(params)
client.indian.panchang.findNakshatra(params)
client.indian.panchang.findSuryaNakshatra(params)
client.indian.panchang.findTithi(params)
client.indian.panchang.findYoga(params)
client.indian.panchang.findKarana(params)
client.indian.panchang.findRituAndAnaya(params)
client.indian.panchang.findAuspiciousTimings(params)
client.indian.panchang.findInauspiciousTimings(params)
client.indian.panchang.findGowriPanchangam(params)
client.indian.panchang.findNivasAndShool(params)
client.indian.panchang.findOtherCalendars(params)
client.indian.panchang.chandrashtama(params)
client.indian.panchang.grahGochar(planet, params)
client.indian.panchang.planetNakshatraTransit(planet, params)
client.indian.panchang.planetRetrogradeTransit(planet, params)
client.indian.panchang.planetCombustionTransit(planet, params)
client.indian.panchang.findChandrabalamAndTarabalam(params)
client.indian.panchang.findPanchakRahita(params)
client.indian.panchang.findUdayLagna(params)
client.indian.panchang.findChoghadiya(params)
client.indian.panchang.monthSunriseSunset(params)
client.indian.panchang.monthNakshatraList(params)
client.indian.panchang.monthTithiList(params)
client.indian.panchang.monthSuryaNakshatraList(params)

Indian Astrology - Kundli

client.indian.kundli.basicAstroDetails(params)
// weekday: 'vedic' changes the day at sunrise, so a birth before sunrise gets the
// previous day's vaar ('civil', the default, changes it at midnight). Also accepted by
// varshphalVarshaPravesh, varshphalBasicAstroDetails and lalKitabVarshphalVarshaPravesh.
client.indian.kundli.basicAstroDetails({ ...params, weekday: 'vedic' })
client.indian.kundli.planetaryPositions(params)
client.indian.kundli.horoscopeChart(params)
client.indian.kundli.vimshottariDasha(params)
client.indian.kundli.kaalSarpaDosha(params)
client.indian.kundli.manglikDosha(params)
client.indian.kundli.ascendantReport(params)
client.indian.kundli.compositeFriendship(params)
client.indian.kundli.bhavaKundli(chartId, params)
client.indian.kundli.sadheSati(params)
client.indian.kundli.ghataChakra(params)
client.indian.kundli.shadbala(params)
client.indian.kundli.gemstoneSuggestion(params)
client.indian.kundli.yoginiDasha(params)
client.indian.kundli.kaalChakraDasha(params)
client.indian.kundli.yogas(params)
client.indian.kundli.pitraDosha(params)
client.indian.kundli.planetAnalysis(params)
client.indian.kundli.grahaDrishti(params)   // Vedic aspects: planets -> houses and planets
client.indian.kundli.sudarshanChakra(params)
// Jaimini
client.indian.kundli.jaiminiPlanetaryPositions(params)
client.indian.kundli.jaiminiPadas(params)
client.indian.kundli.jaiminiKarakamshaLagna(params)
client.indian.kundli.jaiminiCharaDasha(params)
client.indian.kundli.jaiminiSwamsaChart(params)   // atmakaraka, swamsha/lagnamsha signs + chart svg
// Sub Planet
client.indian.kundli.subPlanetPositions(params)
client.indian.kundli.subPlanetChart(params)
// Transit
client.indian.kundli.transitAscendant(params)
client.indian.kundli.transitMoon(params)
// Bhinnashtakvarga
client.indian.kundli.ashtakvarga(params)
client.indian.kundli.sarvashtakavarga(chart, params)
client.indian.kundli.prastharaChakra(params)
// Dasha Analysis
client.indian.kundli.mahaDashaAnalysis(params)
client.indian.kundli.antarDashaAnalysis(params)
client.indian.kundli.pratyantarDashaAnalysis(params)
// Lal Kitab
client.indian.kundli.lalKitabPlanetaryPositions(params)
client.indian.kundli.lalKitabHoroscopeChart(params)
client.indian.kundli.lalKitabHousePosition(params)
client.indian.kundli.lalKitabConjunctions(params)
client.indian.kundli.lalKitabTeva(params)
client.indian.kundli.lalKitabPlanetAnalysis(params)   // params + analysis_planet
client.indian.kundli.lalKitabDasha(params)
client.indian.kundli.lalKitabPlanetTypes(params)
client.indian.kundli.lalKitabMahadashaContent({ maha_dasha: 'saturn' })
client.indian.kundli.lalKitabAntardashaContent({ maha_dasha: 'saturn', antar_dasha: 'mercury' })
client.indian.kundli.lalKitabDebts(params)
client.indian.kundli.lalKitabHouseSignification(params)   // params + house_no (1-12)
// Lal Kitab Varshphal (params + varshphal_year)
client.indian.kundli.lalKitabVarshphalVarshaPravesh(params)
client.indian.kundli.lalKitabVarshphalPlanetaryPositions(params)
client.indian.kundli.lalKitabVarshphalMuntha(params)
client.indian.kundli.lalKitabVarshphalChart(params)
// Additional Kundli Analysis
client.indian.kundli.vargottamaPlanets(params)
client.indian.kundli.bhavBala(params)
client.indian.kundli.shaniAshtamShani(params)
client.indian.kundli.bhavaAnalysis(params)
client.indian.kundli.bhavaGroupPredictions(params)
client.indian.kundli.planetRemedies(params)   // params + analysis_planet

Indian Astrology - Match Making

client.indian.matchMaking.ashtakootMilan(params)
client.indian.matchMaking.dashakootMilan(params)
client.indian.matchMaking.navPanchamYoga(params)
client.indian.matchMaking.basicAstroDetails(params)
client.indian.matchMaking.planetaryPositions(params)
client.indian.matchMaking.vimshottariDasha(params)
client.indian.matchMaking.manglikDosha(params)
client.indian.matchMaking.horoscopeChart(params)

Indian Astrology - Festivals

client.indian.festival.margashirshFestivals(params)
client.indian.festival.ashvinaFestivals(params)
// ... all 12 Hindu calendar month festivals
client.indian.festival.englishCalendarFestivals(params)
client.indian.festival.dateSpecificFestivals(params)
client.indian.festival.findFestival(params)
client.indian.festival.malayalamFestivals(params)
client.indian.festival.tamilFestivals(params)
client.indian.festival.sankrantiFestivals(params)

Western Astrology - Natal

client.western.natal.planetaryPositions(params)   // 18 bodies incl. Vertex (astroapi-8 since 1.10.0; see note below)
client.western.natal.houseCusps(params)
client.western.natal.aspectTable(params)
client.western.natal.natalWheelChart(params)
client.western.natal.generalSignReport(planet, params)
client.western.natal.generalHouseReport(planet, params)
client.western.natal.moonPhases(params)
client.western.natal.ascendantReport(params)
client.western.natal.moonPhaseCalendar(params)
client.western.natal.natalInsights(params)
client.western.natal.arabicLots(params)
client.western.natal.asteroidPositions(params)
client.western.natal.fixedStarsList()
client.western.natal.fixedStarsDetails(params)
client.western.natal.planetaryMidpoints(params)
client.western.natal.eclipse(params)
client.western.natal.declinationsParallels(params)
client.western.natal.aspectPatterns(params)
client.western.natal.chartShape(params)
client.western.natal.otherMinorBodies(params)
client.western.natal.dominants(params)   // params.method: 'TRADITIONAL' | 'MODERN' (required)
client.western.natal.personaChart(params)  // params.persona_planet: 'sun' | 'moon' | ... (required)

// personaChart: the chart for the moment, within the first year of life, that the
// transiting Sun reaches the natal degree of persona_planet. output_include controls
// response size and defaults to 'raw_data' (~21 KB); image tokens are ~0.5 MB per SVG
// and output_include: 'all' returns ~4.3 MB.

// Note: house_system accepts a friendly name ('placidus', 'koch', 'whole-sign', ...)
// or a letter code ('P', 'K', 'W', ...); it is mapped to the letter code the API
// requires before the request is sent. Omit it to use the default (Placidus).

planetaryPositions changed in 1.10.0. It now calls astroapi-8 instead of astroapi-4, so the response includes Vertex (18 bodies instead of 17). Two behaviour changes come with it:

the envelope is { status: 'success', code: 200, message, data } - there is no longer a success key, so code checking res.success === 1 must switch to res.status === 'success' (or just read res.data);

invalid input now rejects with a DivineApiError whose statusCode is 422 (responseBody.error.details names the bad field) instead of resolving with { success: 2 }.

The data array is otherwise unchanged: same fields, same types, identical values for the other 17 bodies.

Western Astrology - Synastry

client.western.synastry.planetaryPositions(params)
client.western.synastry.houseCusps(params)
client.western.synastry.natalWheelChart(params)
client.western.synastry.aspectTable(params)
client.western.synastry.harmoniousAspectReading(params)
client.western.synastry.conflictingAspectReading(params)
client.western.synastry.contrastingAspectReading(params)
client.western.synastry.intenseAspectReading(params)
client.western.synastry.physicalCompatibility(params)
client.western.synastry.emotionalCompatibility(params)
client.western.synastry.sexualCompatibility(params)
client.western.synastry.spiritualCompatibility(params)
client.western.synastry.financialCompatibility(params)

Western Astrology - Transit

client.western.transit.basic(params)    // + transit_day/month/year/hour/min/sec
client.western.transit.customTransit(params) // + transit_day/month/year/hour/min/sec, transit_place/lat/lon/tzone
client.western.transit.daily(params)
client.western.transit.weekly(params)   // + transit_planet (required)
client.western.transit.monthly(params)  // + transit_planet, transit_month, transit_year, transit_place/lat/lon/tzone
client.western.transit.full(params)     // + transit_planet, transit_day/month/year, transit_place/lat/lon/tzone
client.western.transit.planetaryIngress(params)
client.western.transit.planetRetrogradeTransit(params)
client.western.transit.planetCombustionTransit(params)
client.western.transit.house(params)    // + transit_day/month/year/hour/min/sec, transit_place/lat/lon/tzone

Western Astrology - Composite Chart

client.western.composite.planetaryPositions(params)
client.western.composite.houseCusps(params)
client.western.composite.aspectTable(params)
client.western.composite.natalWheelChart(params)

Western Astrology - Planet Returns

client.western.planetReturns.list(params)     // + planet, return_year, return_place/lat/lon/tzone
client.western.planetReturns.details(params)  // + planet, return_key, return_year, return_place/lat/lon/tzone

Western Astrology - Progressions

client.western.progressions.progressedLunarEvents(params)   // + prenatal_type (required)
client.western.progressions.planetaryArcDirections(params)  // + planet, progressed_day/month/year
client.western.progressions.secondaryProgressions(params)   // + progressed_day/month/year/hour/min/sec, progressed_type

Western Astrology - Prenatal

client.western.prenatal.list(params)     // + prenatal_type (required)
client.western.prenatal.details(params)  // + prenatal_key (required)

PDF Reports

The API requires seven branding fields on every PDF request: company_name, company_url, company_email, company_mobile, company_bio, logo_url and footer_text (a few legacy reports also need company_landline). Pass company_mobile even though the SDK types mark it optional. natalReport also needs report_code + theme; the numerology PDFs (predictionReport, numerologyReport) need full_name + gender + report_code.

client.pdf.kundaliSampoorna(params)
client.pdf.kundaliAnanta(params)
client.pdf.kundaliPrakash(params)
client.pdf.matchMaking(params)
client.pdf.governmentJobReport(params)
client.pdf.foreignTravelSettlement(params)
client.pdf.vedicYearly5Year(params)
client.pdf.vedicYearly10Year(params)
client.pdf.vedicYearly15Year(params)
client.pdf.natalReport(params)
client.pdf.natalCoupleReport(params)
client.pdf.predictionReport(params)
client.pdf.numerologyReport(params)

// Optional cover on the 9 Vedic V1 PDFs (kundali, match making, government job,
// foreign travel, yearly): show only your image on page 1
client.pdf.kundaliSampoorna({ ...params, front_image: 'https://example.com/cover.png', hide_frontpage_details: true })

// Reports V2: JSON body + x-api-key header (handled by the SDK). Needs a DivineAPI PDF
// account's apiKey/authToken; a standard API account gets 401 "Invalid Bearer token".
// Returns reportId, htmlUrl, pdfUrl, statusUrl; ready in about 10-30 seconds.
client.pdf.reportsGenerate({ report_type: 'vedic-career-report', ...birth, ...branding })
client.pdf.westernReportsGenerate({ report_type: 'western-inner-moon', tier: 'snapshot', ...birth, ...branding })
// hide_frontpage_details: true shows only front_image on the cover (requires front_image)
client.pdf.reportsGenerate({ report_type: 'vedic-career-report', ...birth, ...branding,
  front_image: 'https://example.com/cover.png', hide_frontpage_details: true })

Numerology

client.numerology.newMobileNumber(params)
client.numerology.analyzeMobileNumber(params)
client.numerology.loshuGrid(params)
client.numerology.zodiacPlanetNumber(params)
client.numerology.luckNumerology(params)
client.numerology.nameNumber(params)
client.numerology.nameCorrection(params)
client.numerology.birthdayNumber(params)
client.numerology.missingNumbers(params)
client.numerology.driverAndConductorNumbers(params)
client.numerology.twoNumbersArrows(params)
client.numerology.threeNumbersArrows(params)
client.numerology.repeatingNumbers(params)
client.numerology.yearlyPrediction(params)
client.numerology.gemstones(params)
client.numerology.coreNumbers(params)   // params.method: 'general' | 'chaldean' | 'pythagorean' (required)

Lifestyle

client.lifestyle.zodiacGiftGuru(params)
client.lifestyle.beautyByStars(params)
client.lifestyle.astroChicPicks(params)

Calculators

client.calculators.flames(params)   // params: { your_name, partner_name }
client.calculators.love(params)

Location

// Place name (at least 3 characters) -> up to 10 matches with lat, lon and timezone
const res = await client.location.search({ place: 'Patna' });
const first = res.data.results[0];   // latitude 25.41667, longitude 85.16667, timezone "Asia/Kolkata"

// timezone_value is the zone's UTC offset today. For a birth date in a zone with
// summer time (e.g. America/New_York: -5 in winter, -4 in summer) work out the offset
// for that date from first.timezone before passing it as tzone.
// Place data (c) GeoNames (geonames.org), CC BY 4.0: res.attribution.

Astro Chatbot

Needs an Astro Chatbot plan on your account. Same apiKey and authToken; the SDK sends them as x-api-key and Authorization: Bearer headers to ask.divineapi.com. Every conversation belongs to one of your end users: one key has many user_ids, each user_id has many session_ids, and the same session_id under two user_ids is two separate sessions.

// First message of a session: send the birth details once (numbers are fine,
// the SDK sends them as the strings the chatbot expects)
const res = await client.chatbot.chat({
  user_id: 'u_8812', session_id: 's_1', message: 'When will I get a job?',
  full_name: 'Priya Sharma', day: 24, month: 5, year: 1996, hour: 14, min: 40,
  gender: 'female', place: 'New Delhi', lat: 28.7041, lon: 77.1025, tzone: 5.5,
  depth: 'standard',          // quick 20 / standard 30 / deep 50 credits
});
console.log(res.answer, res.credits_charged, res.credits_remaining);

// Follow-ups in the same session reuse the stored birth details
await client.chatbot.chat({ user_id: 'u_8812', session_id: 's_1', message: 'And for marriage?',
  school: 'vedic', lens: 'love', language: 'Hindi' });

// Stream the answer: { delta } events, then one { done: true, ... } receipt
for await (const event of client.chatbot.chatStream({ user_id: 'u_8812', session_id: 's_1',
  message: 'What should I focus on this month?' })) {
  if (event.delta) process.stdout.write(event.delta);
}

// Daily horoscope for a date (full birth details on every call)
await client.chatbot.horoscopePrediction({
  user_id: 'u_8812', date: '2026-10-31',
  day: 24, month: 5, year: 1996, hour: 14, min: 40, gender: 'female',
  place: 'New Delhi', lat: 28.7041, lon: 77.1025, tzone: 5.5,
});

await client.chatbot.sessions({ user_id: 'u_8812' });                       // 404 if none yet
await client.chatbot.session({ user_id: 'u_8812', session_id: 's_1' });     // messages + birth_details
await client.chatbot.deleteSession({ user_id: 'u_8812', session_id: 's_1' }); // permanent
await client.chatbot.balance();   // { state: 'active', credits_remaining, expires: 'YYYY-MM-DD' }

Other chat() options: length_cap (short / medium / full), language (any language name, or auto), school (western / vedic / kp / lalkitab), lens (general / career / love / health / money / spiritual), confidence (balanced / definitive / careful), sensitivity (standard / strict), and free text tone, framing, assistant_name, brand_voice, sign_off and style_notes (at most 500 characters). Guardrail replies and failed requests are not charged. A missing user or session is a DivineApiError with statusCode 404, and an out-of-credit account gets status 402.

Error Handling

import { DivineApi, AuthenticationError, RateLimitError, ValidationError, NetworkError } from 'divineapi';

try {
  const result = await client.horoscope.daily({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key or token');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Related repos

Type	Repo
SDK	divineapi-python: Python SDK (`pip install divineapi`)
SDK	divineapi-php: PHP SDK (`composer require divineapi/divineapi`)
REST API	kundli-api: Kundli / Kundali API (Vedic birth chart, dashas, doshas)
REST API	kundli-matching-api: Kundli matching API (Ashtakoot, Dashakoot)
REST API	lal-kitab-api: Lal Kitab API
REST API	panchang-api: Panchang API
REST API	hindu-festival-api: Hindu Festival API
REST API	birth-chart-api: Birth Chart API
REST API	horoscope-api: Horoscope API
REST API	tarot-api: Tarot API
REST API	numerology-api: Numerology API
REST API	astrology-api: Astrology API (overview of all domains)
Model Context Protocol (MCP)	mcp-indian-astrology: Vedic astrology MCP server
MCP	mcp-western-astrology: Western astrology MCP server
MCP	mcp-horoscope-numerology: Horoscope, tarot and numerology MCP server

Support

API reference: developers.divineapi.com
Postman collection: documenter.getpostman.com/view/26759678/2sBYAysU8Y
API status: status.divineapi.com
Help centre: support.divineapi.com
Plans and prices: divineapi.com/pricing
SDK bugs: open an issue in this repo

License

MIT

Navigation Menu

Repository navigation

README.md

README.md

Astrology API Node.js SDK (DivineAPI)

Get your API key

Requirements

Installation

Quick Start

Configuration

API Categories

Horoscope & Tarot

Indian Astrology - Panchang

Indian Astrology - Kundli

Indian Astrology - Match Making

Indian Astrology - Festivals

Western Astrology - Natal

Western Astrology - Synastry

Western Astrology - Transit

Western Astrology - Composite Chart

Western Astrology - Planet Returns

Western Astrology - Progressions

Western Astrology - Prenatal

PDF Reports

Numerology

Lifestyle

Calculators

Location

Astro Chatbot

Error Handling

Related repos

Support

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Astrology API Node.js SDK (DivineAPI)

Get your API key

Requirements

Installation

Quick Start

Configuration

API Categories

Horoscope & Tarot

Indian Astrology - Panchang

Indian Astrology - Kundli

Indian Astrology - Match Making

Indian Astrology - Festivals

Western Astrology - Natal

Western Astrology - Synastry

Western Astrology - Transit

Western Astrology - Composite Chart

Western Astrology - Planet Returns

Western Astrology - Progressions

Western Astrology - Prenatal

PDF Reports

Numerology

Lifestyle

Calculators

Location

Astro Chatbot

Error Handling

Related repos

Support

License