MCP server RoxyAPI

@roxyapi/sdk

TypeScript SDK for astrology, Vedic astrology, numerology, tarot, and more.

One API key. Fully typed. Verified against NASA JPL Horizons.

The fastest way to add natal charts, daily horoscopes, synastry, Vedic kundli, tarot spreads, numerology, human design bodygraphs, and transit forecasts to Node.js apps, backends, and AI agents. 18+ domains behind a single Roxy subscription, interpretations in 10+ languages.

Install

npm install @roxyapi/sdk
# or
bun add @roxyapi/sdk

Start with one call

Get real product value with a single typed call. No setup beyond your API key.

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data, error } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
if (error) throw error;
console.log(data.overview, data.love, data.luckyNumber);

Then expand into charts, compatibility, numerology, tarot, and more.

Quick start

import { createRoxy } from '@roxyapi/sdk';

// Retries 429, 500, 502, 503 and 504 by default. Optional settings, shown with their defaults:
// createRoxy(key, { maxRetries: 2, initialDelayMs: 500, maxDelayMs: 30000 })
const roxy = createRoxy(process.env.ROXY_API_KEY!);

// Step 1: geocode the birth city once. Every chart endpoint takes these three values.
const { data: place, error: lookupError } = await roxy.location.searchCities({ query: { q: 'London' } });
if (lookupError) throw lookupError;
const { latitude, longitude, timezone } = place.cities[0];

// Step 2: a Western natal chart. `timezone` is the IANA string from the lookup
// ("Europe/London"); the server resolves it to the DST-correct offset for the
// date of the chart.
const { data: chart, error: chartError } = await roxy.astrology.generateNatalChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
});
if (chartError) throw chartError;
// `planets` is a list: find a body by its `name`.
console.log(chart.planets.find((p) => p.name === 'Moon')?.sign);

// Step 3: the same birth as a Vedic kundli. Same inputs, sidereal zodiac.
const { data: kundli, error: kundliError } = await roxy.vedicAstrology.generateBirthChart({
  body: { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone },
});
if (kundliError) throw kundliError;
// `meta.Moon.rashi` is a string; `meta.Moon.nakshatra` is an object, so read `.name`.
console.log(kundli.meta.Moon?.rashi, kundli.meta.Moon?.nakshatra.name);

createRoxy sets the base URL (https://roxyapi.com/api/v2) and injects the auth header and SDK identification header on every request. Every method returns { data, error, response }; check error first, or pass throwOnError: true in the call options to have failures throw and data typed as always present (see Error handling). A network failure (DNS, timeout, connection reset) is not an API error: the call throws, so wrap calls in try/catch where that matters.

Domains

Namespace	What it covers
roxy.astrology	Western astrology API for natal birth charts, daily, weekly, monthly, and yearly horoscopes with unique content per s...
roxy.vedicAstrology	Vedic astrology (Jyotish) and KP API for kundli generation with the sixteen Shodasavarga divisional charts (D1 to D60...
roxy.forecast	Astrology forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons,...
roxy.humanDesign	Human Design API that generates the full bodygraph from a birth moment: type, strategy, inner authority, profile, def...
roxy.chineseAstrology	Chinese zodiac and BaZi astrology API: Four Pillars charts, Chinese zodiac signs and the Chinese lunisolar calendar f...
roxy.fengShui	Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mount...
roxy.mesoamericanAstrology	Calculate Mayan astrology day signs, the Tzolkin sacred round, the Haab year, the full Long Count and the Aztec tonal...
roxy.vastu	Vastu Shastra API for directional home and plot analysis: entrance padas with the classical effect of each of the 32...
roxy.numerology	Numerology API for life path numbers, complete numerology charts and compatibility, in both Pythagorean and Chaldean...
roxy.kabbalah	Kabbalah API for gematria, the 72 names, the Tree of Life and the Hebrew birthday
roxy.tarot	Tarot reading API with the complete 78-card Rider-Waite-Smith deck and card meanings for love, career, health, and sp...
roxy.biorhythm	Biorhythm API for entertainment and reflection, with 10 model cycle types across 3 primary (physical, emotional, inte...
roxy.ayurveda	Ayurveda API for dosha profiles, the dinacharya daily routine and the ritucharya seasonal regimen, with a verse cited...
roxy.iching	I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career...
roxy.crystals	Crystal healing API covering the most popular and widely-searched healing crystals and gemstones, from Amethyst and R...
roxy.dreams	Dream interpretation API with a 2,200+ symbol dream dictionary and psychological meanings covering animals, objects,...
roxy.angelNumbers	Angel numbers API with meanings for 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, and 75+ sequences covering eve...
roxy.location	Timezone and location API with city search and geocoding across 5,180,000+ cities, towns and villages in 240+ countri...
roxy.usage	Monitor your API usage, check rate limits, and track request consumption
roxy.reports	Branded reports built from the API: a natal chart and more as a print-ready PDF, self-contained HTML or Markdown, whi...
roxy.languages	List the response languages accepted by the lang query parameter on every i18n-aware endpoint

Most-used endpoints

The highest-demand endpoints by domain, in the order you are most likely to ship them. Every example below reads the same birth through a different domain, and every coordinate comes from one location lookup at the top: one API key, one lookup, and eighteen domains that compose into a single product instead of eighteen separate ones. Full catalog in the API reference.

Location first: one lookup feeds every chart

Every chart, horoscope, panchang, dasha, dosha, synastry and compatibility endpoint needs latitude, longitude and timezone. Never ask users to type coordinates. Look the city up once and reuse the result in every domain below.

// One lookup feeds every chart below. `timezone` is the IANA name from the city
// record; the server resolves it to the DST-correct offset for the date of each chart.
const { data: place, error } = await roxy.location.searchCities({ query: { q: 'New York' } });
if (error) throw error;
const { latitude, longitude, timezone } = place.cities[0];
const birth = { date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone };

// A second person for the two-chart calls (synastry, Guna Milan, Human Design connection).
const { data: london, error: error2 } = await roxy.location.searchCities({ query: { q: 'London' } });
if (error2) throw error2;
const { latitude: lat2, longitude: lon2, timezone: tz2 } = london.cities[0];
const partner = { date: '1992-07-22', time: '09:00:00', latitude: lat2, longitude: lon2, timezone: tz2 };

1. Western astrology API (natal chart, daily horoscope, synastry)

Natal chart products, daily horoscope features, dating and compatibility apps, and lunar-cycle wellness apps start here.

// Natal chart. The most requested Western call, run once at onboarding.
// `birth` carries the latitude, longitude and timezone from the location lookup above.
const { data: natal } = await roxy.astrology.generateNatalChart({ body: birth });
// natal.planets[n].name, .sign, .house, .interpretation?.summary; natal.ascendant.sign; natal.aspects

// Daily horoscope. The highest per-user call frequency in the catalog: daily content, streaks, push.
const { data: horoscope } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });
// horoscope.overview, horoscope.love, horoscope.career, horoscope.column, horoscope.events, horoscope.luckyNumber

// Synastry. Full inter-aspect analysis between two charts, the relationship feature of dating apps.
const { data: synastry } = await roxy.astrology.calculateSynastry({
  body: { person1: birth, person2: partner },
});
// synastry.compatibilityScore, synastry.interAspects, synastry.analysis.strengths

// Moon phase. A zero-setup GET for wellness, cycle-tracking and meditation apps.
const { data: moon } = await roxy.astrology.getCurrentMoonPhase({});
// moon.phase, moon.illumination, moon.sign, moon.meaning?.description

2. Vedic astrology API (kundli, panchang, dasha, Guna Milan, KP)

Kundli generators, matrimonial matching, muhurta and panchang apps, and KP practitioners. The same birth object, read sidereally.

// Vedic kundli. The same birth read sidereally: `birth` reuses the location lookup above.
const { data: kundli } = await roxy.vedicAstrology.generateBirthChart({ body: birth });
// kundli.meta.Moon.rashi, kundli.meta.Moon.nakshatra, kundli.houses, kundli.combustion

// Detailed panchang. Tithi, nakshatra, yoga, karana, rahu kaal and the muhurtas for a date and place.
const { data: panchang } = await roxy.vedicAstrology.getDetailedPanchang({
  body: { date: '2026-10-01', latitude, longitude, timezone },
});
// panchang.tithi, panchang.nakshatra, panchang.rahuKaal, panchang.abhijitMuhurta

// Vimshottari dasha. The mahadasha, antardasha and pratyantardasha running right now.
const { data: dasha } = await roxy.vedicAstrology.getCurrentDasha({ body: birth });
// dasha.mahadasha, dasha.antardasha, dasha.remainingInMahadasha

// Mangal Dosha. The most asked matrimonial check.
const { data: dosha } = await roxy.vedicAstrology.checkManglikDosha({ body: birth });
// dosha.present; dosha.severity and dosha.remedies are set only when present is true

// Guna Milan. The 36-point Ashtakoota score behind kundli matching, both people from the lookups above.
const { data: milan } = await roxy.vedicAstrology.calculateGunMilan({
  body: { person1: birth, person2: partner },
});
// milan.total, milan.percentage, milan.isCompatible, milan.breakdown

// KP ruling planets. Horary answers at the moment of the question, for the place looked up above.
const { data: kp } = await roxy.vedicAstrology.getKpRulingPlanets({
  body: { latitude, longitude, timezone },
});
// kp.dayLord, kp.moonSublord, kp.rulingPlanets

3. Astrology forecast API (transit forecast, cross-domain timeline)

Forecast feeds, transit alerts and timing tools. One call returns a dated, significance-scored event list; the timeline variant merges Vedic dasha boundaries and biorhythm critical days into the same list, which no single-domain API can do.

// Transit forecast. Transit-to-natal aspects, sign ingresses and retrograde stations over a window.
// `birthData` is the same `birth` object: date, time, latitude, longitude, timezone.
const { data: transits } = await roxy.forecast.forecastTransits({
  body: { birthData: birth, startDate: '2026-10-01', endDate: '2026-10-31' },
});
// transits.count, transits.events[n].date, .type, .body, .target, .aspect, .significance

// Cross-domain timeline. The same window with Vedic dasha boundaries and biorhythm critical days merged in.
const { data: timeline } = await roxy.forecast.generateTimeline({
  body: { birthData: birth, startDate: '2026-10-01', endDate: '2026-10-31' },
});
// timeline.events[n].domain ('western' | 'vedic' | 'biorhythm'), .description, .significance

4. Human Design API (bodygraph, connection)

Self-discovery apps, coaching bots and compatibility products. The full bodygraph is one call, and the Design side is solved on the exact 88-degree solar arc rather than approximated as calendar days.

// Bodygraph. Type, strategy, authority, profile, definition, centers, channels and all 26 gates in one call.
// Human Design needs only the birth instant, so it takes the date, time and timezone from the lookup above.
const { data: hd } = await roxy.humanDesign.generateBodygraph({
  body: { date: birth.date, time: birth.time, timezone: birth.timezone },
});
// hd.type, hd.strategy, hd.authority, hd.profile, hd.definition, hd.incarnationCross.name, hd.centers, hd.channels, hd.gates

// Connection. Two bodygraphs combined, each of the 36 channels classified by how the pair forms it.
const { data: connection } = await roxy.humanDesign.calculateConnection({
  body: {
    personA: { date: birth.date, time: birth.time, timezone: birth.timezone },
    personB: { date: partner.date, time: partner.time, timezone: partner.timezone },
  },
});
// connection.totalChannels, connection.summary.electromagnetic, connection.combinedDefinition

5. Chinese zodiac API (BaZi four pillars, zodiac animal, almanac)

BaZi readings, zodiac content and Tong Shu date pages. The school splits that make two calculators disagree (dayBoundary, yearBoundary, hourClock) are typed request parameters with named defaults.

// BaZi Four Pillars. The anchor call of the domain, from the same birth instant as every chart above.
// Each response echoes the `conventions` it was computed under, so a chart can be reproduced, not guessed.
const { data: bazi } = await roxy.chineseAstrology.generateBaziChart({
  body: { date: birth.date, time: birth.time, timezone: birth.timezone },
});
// bazi.pillars[n].position ('year' | 'month' | 'day' | 'hour'), .stem.element, .branch.animal, .tenGod.name
// bazi.dayMaster.element, bazi.zodiacAnimal, bazi.fiveElements, bazi.conventions

// Chinese zodiac animal. Defaults `yearBoundary` to the Lunar New Year, the folk rule people mean
// when they ask which animal they are. Pass 'li-chun' for the classical BaZi boundary.
const { data: animal } = await roxy.chineseAstrology.calculateZodiacAnimal({ body: { date: birth.date } });
// animal.animal.name, animal.animal.element, animal.element (the year stem element), animal.interpretation

// Almanac day. The Tong Shu view of a date: day officer, mansion, clash animal, favours and avoids.
const { data: almanac } = await roxy.chineseAstrology.getAlmanacDay({ path: { date: '2026-10-01' } });
// almanac.dayPillar, almanac.dayOfficer, almanac.clashAnimal, almanac.favours, almanac.avoids

6. Feng shui API (Kua number, flying star chart)

Kua numbers with the Eight Mansions map, Xuan Kong flying star charts for any of the nine periods and 24 mountains, annual and monthly star plates, and the annual afflictions.

// Kua number. One birth date and a gender give the personal directions everything else reads off.
const { data: kua } = await roxy.fengShui.calculateKuaNumber({ body: { date: birth.date, gender: 'female' } });
// kua.kua, kua.group ('east' | 'west'), kua.trigram.english, kua.sectors[n].direction, .nature, .rank

// Flying star natal chart. Period plus facing gives the nine palaces with base, mountain and water stars.
// Send `facing` (a mountain id like 'bing' or a compass label like 'S2') or `facingDegrees`, not neither.
const { data: stars } = await roxy.fengShui.generateFlyingStarChart({ body: { period: 9, facing: 'S2' } });
// stars.facing.label, stars.sitting.label, stars.structure.name, stars.palaces[n].palace, .base, .mountain, .water, .reading

7. Mayan astrology API (Tzolkin day sign, full Maya chart)

Maya day signs, the Haab and Long Count, and the Aztec tonalpohualli, every value a function of the date under a typed correlation convention echoed back in conventions.

// Tzolkin day sign. The most asked Maya question, answered from a date alone.
const { data: tzolkin } = await roxy.mesoamericanAstrology.calculateTzolkin({ body: { date: birth.date } });
// tzolkin.daySign, tzolkin.daySignName, tzolkin.number, tzolkin.trecena, tzolkin.reading

// Full Maya chart. Tzolkin, Haab, Long Count, Calendar Round, Lord of the Night, Year Bearer and the Cruz Maya.
const { data: maya } = await roxy.mesoamericanAstrology.generateMayanChart({ body: { date: birth.date } });
// maya.tzolkin, maya.haab, maya.longCount, maya.calendarRound, maya.yearBearer, maya.cross, maya.conventions.correlation

8. Vastu Shastra API (entrance analysis, room compliance)

Home and plot analysis from typed geometry. Every verdict carries a source object naming the text, chapter and verse it rests on, or a convention label where the texts are silent.

// Entrance analysis. Plot, facing and door in; the pada, its devata, the classical effect and the recommended padas out.
const { data: entrance } = await roxy.vastu.calculateEntrancePada({
  body: { plot: { width: 30, depth: 40, unit: 'feet' }, facing: 'North', doorPosition: 0.4 },
});
// entrance.pada, entrance.devata, entrance.effect, entrance.auspiciousness, entrance.recommendedPadas, entrance.source

// Room compliance. A verdict per room with the verse or the convention it rests on, and a scored composite.
const { data: rooms } = await roxy.vastu.calculateRoomCompliance({
  body: {
    plot: { width: 30, depth: 40, unit: 'feet' },
    facing: 'North',
    rooms: [
      { type: 'kitchen', direction: 'Southeast' },
      { type: 'master-bedroom', direction: 'Southwest' },
      { type: 'puja', direction: 'Northeast' },
    ],
  },
});
// rooms.score, rooms.rooms[n].type, .verdict, .idealDirections, .source

9. Numerology API (life path, full chart, personal year)

Works from the birth date and name alone, no coordinates, which makes it the easiest domain to integrate.

// Life Path. The most searched numerology number, from the birth date alone.
const { data: lifePath } = await roxy.numerology.calculateLifePath({ body: { year: 1990, month: 1, day: 15 } });
// lifePath.number, lifePath.type ('single' | 'master'), lifePath.meaning

// Full numerology chart. All six core numbers plus karmic lessons, pinnacles and the personal year in one call.
const { data: numerology } = await roxy.numerology.generateNumerologyChart({
  body: { fullName: 'Jane Smith', year: 1990, month: 1, day: 15 },
});
// numerology.coreNumbers.lifePath, .expression, .soulUrge, numerology.additionalInsights.personalYear

// Personal Year. The annual theme, the January feature of every numerology app.
const { data: personalYear } = await roxy.numerology.calculatePersonalYear({ body: { month: 1, day: 15, year: 2026 } });
// personalYear.personalYear, personalYear.theme, personalYear.advice

10. Kabbalah API (gematria, birth profile)

Gematria of a Latin name under a declared transliteration convention, the 72 names, the Tree of Life, and a Hebrew birthday computed from the same birth instant as every chart above.

// Gematria. A Latin name transliterated under a declared convention, ten ciphers, each with its tradition and source.
const { data: gematria } = await roxy.kabbalah.calculateGematria({ body: { text: 'Sarah' } });
// gematria.chosen.hebrew, gematria.values[n].id, .name, .value, .tradition; gematria.matches, gematria.conventions

// Birth profile. The Hebrew date and birthday, the three birth angels and the birth sephirah from the instant above.
const { data: kabbalah } = await roxy.kabbalah.generateBirthProfile({
  body: { date: birth.date, time: birth.time, timezone: birth.timezone },
});
// kabbalah.hebrewDate, kabbalah.hebrewBirthday, kabbalah.angels, kabbalah.sephirah

11. Tarot API (daily card, three-card, Celtic Cross, yes or no)

The complete 78-card deck with meanings for love, career, health and spirit. Pass a seed per user for deterministic once-per-day draws.

// Daily card. The body takes two optional fields: `seed` (a stable id per user; the same
// seed and date always return the same card, omit it for an anonymous card) and `date`
// (YYYY-MM-DD, defaults to today in UTC).
const { data: card } = await roxy.tarot.getDailyCard({ body: { seed: 'user-42' } });
// card.card.name, card.card.reversed, card.card.imageUrl, card.dailyMessage

// Three-card spread. Past, present, future: the most drawn spread on every tarot platform.
const { data: three } = await roxy.tarot.castThreeCard({ body: { question: 'My next quarter', seed: 'user-42' } });
// three.positions[n].name, .card.name, .interpretation; three.summary

// Celtic Cross. The ten-position professional reading.
const { data: celtic } = await roxy.tarot.castCelticCross({ body: { question: 'What should I focus on?', seed: 'user-42' } });
// celtic.positions[n].name, .card.name, .interpretation; celtic.summary

// Yes or no. One card, one answer, with its strength.
const { data: answer } = await roxy.tarot.castYesNo({ body: { question: 'Should I take the offer?' } });
// answer.answer ('Yes' | 'No' | 'Maybe'), answer.strength, answer.card.name

12. Biorhythm API (reading, forecast)

Ten cycle types across primary, secondary and extended cycles, for wellness, productivity, sports and couples apps.

// Biorhythm reading. All ten cycles for a date, from the same birth date as every chart above.
const { data: bio } = await roxy.biorhythm.getReading({ body: { birthDate: birth.date, targetDate: '2026-10-01' } });
// bio.cycles.physical.value, .phase; bio.energyRating, bio.overallPhase, bio.criticalAlerts, bio.interpretation

// Forecast. Every cycle for every day of a window, with the best and worst days named.
const { data: bioForecast } = await roxy.biorhythm.getForecast({
  body: { birthDate: birth.date, startDate: '2026-10-01', endDate: '2026-10-31' },
});
// bioForecast.summary.bestDay, .worstDay, .averageEnergy; bioForecast.days[n].date, .physical, .emotional, .intellectual, .isCritical