SDK (TypeScript / Python)

npm install @roxyapi/sdk

bun add @roxyapi/sdk

pnpm add @roxyapi/sdk

yarn add @roxyapi/sdk

pip install roxy-sdk

uv add roxy-sdk

poetry add roxy-sdk

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

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

// Daily horoscope
const { data } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

// Numerology life path
const { data: lp } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
});

// Tarot Celtic Cross spread
const { data: reading } = await roxy.tarot.castCelticCross({
  body: { question: 'What should I focus on this month?' },
});

from roxy_sdk import create_roxy

roxy = create_roxy("your-api-key")

# Daily horoscope
horoscope = roxy.astrology.get_daily_horoscope(sign="aries")

# Numerology life path
lp = roxy.numerology.calculate_life_path(year=1990, month=1, day=15)

# Tarot Celtic Cross spread
reading = roxy.tarot.cast_celtic_cross(question="What should I focus on this month?")

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

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

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ["ROXY_API_KEY"])

const { data } = await roxy.location.searchCities({
  query: { q: 'Mumbai, India' },
});

// Response: { total, limit, offset, cities: [...] }
const { latitude, longitude, timezone } = data.cities[0];

const { data: chart } = await roxy.vedicAstrology.generateBirthChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude,
    longitude,
    timezone, // IANA string like "Asia/Kolkata" — server resolves DST for the chart date
  },
});

result = roxy.location.search_cities(q="Mumbai, India")

# Response: { "total", "limit", "offset", "cities": [...] }
city = result["cities"][0]

chart = roxy.vedic_astrology.generate_birth_chart(
    date="1990-01-15", time="14:30:00",
    latitude=city["latitude"], longitude=city["longitude"],
    timezone=city["timezone"],  # IANA string; server resolves DST for the chart date
)

const { data, error } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'scorpio' },
});

if (error) {
  console.error(error);
} else {
  console.log(data.overview); // General daily forecast
  console.log(data.love);     // Love and relationship forecast
  console.log(data.career);   // Career outlook
}

horoscope = roxy.astrology.get_daily_horoscope(sign="scorpio")
print(horoscope["overview"])  # General daily forecast
print(horoscope["love"])      # Love and relationship forecast
print(horoscope["career"])    # Career outlook

const { data } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
});

console.log(data.number); // e.g. 7
console.log(data.type);   // "single" | "master"

result = roxy.numerology.calculate_life_path(year=1990, month=1, day=15)
print(result["number"])  # e.g. 7
print(result["type"])    # "single" | "master"

const { data } = await roxy.vedicAstrology.generateBirthChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 5.5,
  },
});

// Iterate rashis (aries..pisces) for the 12-sign chart
for (const rashi of ['aries', 'taurus', 'gemini'] as const) {
  console.log(rashi, data[rashi].signs); // planets in this rashi
}

// Or look up any planet directly
console.log(data.meta.Sun.rashi);       // "Capricorn"
console.log(data.meta.Moon.nakshatra);  // nakshatra metadata

chart = roxy.vedic_astrology.generate_birth_chart(
    date="1990-01-15", time="14:30:00",
    latitude=28.6139, longitude=77.209, timezone=5.5,
)

# Iterate rashis for the 12-sign chart
for rashi in ["aries", "taurus", "gemini"]:
    print(rashi, chart[rashi]["signs"])

# Or look up any planet directly
print(chart["meta"]["Sun"]["rashi"])       # "Capricorn"
print(chart["meta"]["Moon"]["nakshatra"])  # nakshatra metadata

const { data } = await roxy.astrology.generateNatalChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 5.5,
  },
});

console.log(data.planets.length);  // 13 (incl. lunar nodes and Chiron)
console.log(data.houses.length);   // 12
console.log(data.ascendant);
console.log(data.midheaven);

natal = roxy.astrology.generate_natal_chart(
    date="1990-01-15", time="14:30:00",
    latitude=28.6139, longitude=77.209, timezone=5.5,
)

print(len(natal["planets"]))   # 13
print(len(natal["houses"]))    # 12
print(natal["ascendant"])
print(natal["midheaven"])

const { data } = await roxy.tarot.getDailyCard({ body: { seed: 'user-123' } });
console.log(data.card.name);    // e.g. "The Star"
console.log(data.dailyMessage); // concise daily guidance
console.log(data.card.meaning); // full card interpretation

card = roxy.tarot.get_daily_card(seed="user-123")
print(card["card"]["name"])      # e.g. "The Star"
print(card["dailyMessage"])      # concise daily guidance
print(card["card"]["meaning"])   # full card interpretation

const { data } = await roxy.angelNumbers.getAngelNumber({
  path: { number: '1111' },
});
console.log(data.coreMessage);       // Short divine message summary
console.log(data.meaning.spiritual); // Spiritual interpretation
console.log(data.meaning.love);      // Love / relationship meaning

result = roxy.angel_numbers.get_angel_number(number="1111")
print(result["coreMessage"])          # Short divine message summary
print(result["meaning"]["spiritual"]) # Spiritual interpretation
print(result["meaning"]["love"])      # Love / relationship meaning

const { data } = await roxy.usage.getUsageStats();
console.log(`${data.usedThisMonth} / ${data.requestsPerMonth} requests used`);

stats = roxy.usage.get_usage_stats()
print(f"{stats['usedThisMonth']} / {stats['requestsPerMonth']} requests used")

const { data } = await roxy.tarot.getDailyCard({
  body: { date: '2026-04-22' },
  query: { lang: 'es' },
});

card = roxy.tarot.get_daily_card(date="2026-04-22", lang="es")

// Already async — every method returns a Promise
const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });

import asyncio
from roxy_sdk import create_roxy

async def main():
    roxy = create_roxy("your-api-key")
    horoscope = await roxy.astrology.get_daily_horoscope_async(sign="aries")
    card = await roxy.tarot.get_daily_card_async()
    print(horoscope, card)

asyncio.run(main())

const { data, error } = await roxy.tarot.castYesNo({
  body: { question: 'Should I take this opportunity?' },
});

if (error) {
  switch (error.code) {
    case 'validation_error':
      console.error('Bad input:', error.error);
      break;
    case 'rate_limit_exceeded':
      console.error('Monthly quota reached');
      break;
    default:
      console.error('API error:', error.code, error.error);
  }
} else {
  console.log(data.answer); // "Yes" | "No" | "Maybe"
}

from roxy_sdk import create_roxy, RoxyAPIError

try:
    result = roxy.tarot.cast_yes_no(question="Should I take this opportunity?")
    print(result["answer"])  # "Yes" | "No" | "Maybe"
except RoxyAPIError as e:
    if e.code == "validation_error":
        print(f"Bad input: {e.error}")
    elif e.code == "rate_limit_exceeded":
        print("Monthly quota reached")
    else:
        print(f"API error: {e.code} {e.error}")