Python SDK for astrology, Vedic astrology, tarot, numerology, and more.
One API key. Sync and async (every method has an _async suffix). 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 FastAPI, Django, Flask, or any Python project. 18+ domains behind a single Roxy subscription, interpretations in 10+ languages.
pip install roxy-sdkGet real product value with a single typed call. No setup beyond your API key.
from roxy_sdk import create_roxy
roxy = create_roxy("your-api-key")
horoscope = roxy.astrology.get_daily_horoscope(sign="aries")
print(horoscope["overview"], horoscope["love"], horoscope["luckyNumber"])Then expand into charts, compatibility, tarot, numerology, and more.
from roxy_sdk import create_roxy
roxy = create_roxy("your-api-key")
# Step 1: geocode the birth city (required for any chart endpoint)
result = roxy.location.search_cities(q="London, UK")
city = result["cities"][0]
lat, lng, tz = city["latitude"], city["longitude"], city["timezone"]
# Step 2: Western natal chart. `timezone` can be the IANA string ("Europe/London").
# The server resolves it to the DST-correct offset for the chart's own date.
natal = roxy.astrology.generate_natal_chart(
date="1990-01-15",
time="14:30:00",
latitude=lat,
longitude=lng,
timezone=tz,
)
# Vedic kundli takes the same inputs (timezone optional, defaults to 5.5 IST).
kundli = roxy.vedic_astrology.generate_birth_chart(
date="1990-01-15",
time="14:30:00",
latitude=lat,
longitude=lng,
timezone=tz,
)Get your API key at roxyapi.com/pricing. Free test keys available on the interactive docs.
Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs latitude, longitude, and (for Western) timezone. Never ask users to type coordinates. Always call roxy.location.search_cities(q=city) first and feed the result into the chart call.
result = roxy.location.search_cities(q="Tokyo")
city = result["cities"][0]
lat, lng, tz = city["latitude"], city["longitude"], city["timezone"]
# `tz` is the IANA string ("Asia/Tokyo"). Pass it straight into any chart
# endpoint and the server resolves it to the DST-correct offset for the chart's
# own date. If you prefer a decimal, city["utcOffset"] also works.| Domain | Property | Methods | What it covers |
|---|---|---|---|
| Western Astrology | roxy.astrology |
39 | Western astrology API for natal birth charts, daily, weekly, monthly, and yearly horoscopes with unique content per s... |
| Vedic Astrology | roxy.vedic_astrology |
55 | Vedic astrology (Jyotish) and KP API for kundli generation with 15 divisional charts (D1-D60), Ashtakoot Gun Milan ku... |
| Forecast | roxy.forecast |
5 | Forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm... |
| Human Design | roxy.human_design |
12 | Generate the full Human Design bodygraph from a birth moment: type, strategy, inner authority, profile, definition, i... |
| Chinese Astrology | roxy.chinese_astrology |
16 | Calculate BaZi Four Pillars charts, Chinese zodiac signs, and the Chinese lunisolar calendar from any birth moment: y... |
| Feng Shui | roxy.feng_shui |
11 | Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mount... |
| Mesoamerican Astrology | roxy.mesoamerican_astrology |
18 | Calculate Mayan astrology day signs, the Tzolkin sacred round, the Haab year, the full Long Count and the Aztec tonal... |
| Vastu | roxy.vastu |
10 | Vastu Shastra API for directional home and plot analysis: entrance padas with the classical effect of each of the 32... |
| Numerology | roxy.numerology |
20 | Numerology API to calculate life path, expression, soul urge, personality, and maturity numbers, with Pinnacle and Ch... |
| Kabbalah | roxy.kabbalah |
12 | Kabbalah API for gematria, the 72 names, the Tree of Life and the Hebrew birthday, from one key |
| Tarot | roxy.tarot |
10 | Tarot reading API with the complete 78-card Rider-Waite-Smith deck and card meanings for love, career, health, and sp... |
| Biorhythm | roxy.biorhythm |
6 | The most complete biorhythm API: 10 cycle types across 3 primary (physical, emotional, intellectual), 4 secondary (in... |
| Ayurveda | roxy.ayurveda |
8 | Ayurveda API for dosha profiles, the dinacharya daily routine and the ritucharya seasonal regimen, with a verse cited... |
| I Ching | roxy.iching |
9 | I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career... |
| Crystals | roxy.crystals |
12 | Crystal healing API covering the most popular and widely-searched healing crystals and gemstones, from Amethyst and R... |
| Dreams | roxy.dreams |
5 | Dream interpretation API with a 2,000+ symbol dream dictionary and psychological meanings covering animals, objects,... |
| Angel Numbers | roxy.angel_numbers |
4 | Angel numbers API with meanings for 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, and 75+ sequences covering eve... |
| Location | roxy.location |
3 | Location and timezone API with city search and geocoding across 235,000+ cities in 240+ countries, returning latitude... |
| Usage | roxy.usage |
1 | Monitor your API usage, check rate limits, and track request consumption |
| Languages | roxy.languages |
2 | List the response languages accepted by the lang query parameter on every i18n-aware endpoint |
The highest-demand endpoints by domain, in the order you are most likely to ship them. Each block shows the most-searched API call in that domain so you can pick the feature that drives the most user value first. Full endpoint catalog in the API reference.
The global astrology app market is $6.27B and almost entirely Western. These endpoints power zodiac dating apps, Co-Star-style natal chart products, daily horoscope features, and lunar-cycle wellness apps.
# Natal chart. The #1 Western query, called on every onboarding.
natal = roxy.astrology.generate_natal_chart(
date="1990-01-15", time="14:30:00",
latitude=40.7128, longitude=-74.006, timezone="America/New_York",
)
# Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
horoscope = roxy.astrology.get_daily_horoscope(sign="aries")
# horoscope["overview"], horoscope["love"], horoscope["career"], horoscope["luckyNumber"]
# Synastry. The dating-app pro-tier feature, full inter-aspect analysis.
synastry = roxy.astrology.calculate_synastry(
person1={"date": "1990-01-15", "time": "14:30:00", "latitude": 40.71, "longitude": -74.01, "timezone": -5},
person2={"date": "1992-07-22", "time": "09:00:00", "latitude": 51.51, "longitude": -0.13, "timezone": 1},
)
# synastry["compatibilityScore"], synastry["interAspects"], synastry["analysis"]["strengths"]
# Moon phase. Viral for wellness, cycle-tracking, meditation apps.
moon = roxy.astrology.get_current_moon_phase()The depth moat. India astrology market: $163M in 2024, projected $1.8B by 2030 (49% CAGR). Kundli, panchang, dasha, dosha, and KP are the five Google-dominant queries for every matrimonial platform, kundli generator, and muhurat app.
# Vedic kundli. Top India astrology keyword. Entry point for every Jyotish product.
kundli = roxy.vedic_astrology.generate_birth_chart(
date="1990-01-15", time="14:30:00",
latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
)
# Panchang. Tithi, nakshatra, yoga, karana, rahu kaal, abhijit muhurta in one call.
panchang = roxy.vedic_astrology.get_detailed_panchang(
date="2026-04-22", latitude=28.6139, longitude=77.209,
)
# Vimshottari dasha. Highest-value single-shot Vedic query.
dasha = roxy.vedic_astrology.get_current_dasha(
date="1990-01-15", time="14:30:00",
latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
)
# Mangal Dosha. Most-asked matrimonial question in India.
dosha = roxy.vedic_astrology.check_manglik_dosha(
date="1990-01-15", time="14:30:00",
latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
)
# Guna Milan. 36-point Ashtakoota matrimonial compatibility score.
milan = roxy.vedic_astrology.calculate_gun_milan(
person1={"date": "1990-01-15", "time": "14:30:00", "latitude": 28.61, "longitude": 77.20},
person2={"date": "1992-07-22", "time": "09:00:00", "latitude": 19.07, "longitude": 72.87},
)
# KP ruling planets. Horary answers for "will X happen" questions in real time.
kp = roxy.vedic_astrology.get_kp_ruling_planets(
latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
)Commodity content with durable demand. life path number calculator is among the highest-volume spiritual searches globally. Works without birth time, the easiest domain to integrate.
# Life Path. The #1 numerology keyword, every calculator page starts here.
lp = roxy.numerology.calculate_life_path(year=1990, month=1, day=15)
# lp["number"], lp["type"] ("single" | "master"), lp["meaning"]
# Full numerology chart. Premium one-shot: all six core numbers plus karmic, personal year.
chart = roxy.numerology.generate_numerology_chart(
full_name="Jane Smith", year=1990, month=1, day=15,
)
# Personal Year. Annual forecast, drives January traffic spikes.
pyear = roxy.numerology.calculate_personal_year(month=1, day=15, year=2026)High search volume, evergreen. The tarot card database is the highest per-endpoint call count in the catalog because apps fetch once and cache.
# Daily card. Stickiest tarot feature. Seed per user for deterministic once-per-day behavior.
card = roxy.tarot.get_daily_card(seed="user-42")
# card["card"]["name"], card["card"]["imageUrl"], card["dailyMessage"]
# Celtic Cross. Professional-reader spread. Premium-tier, ten positions.
cc = roxy.tarot.cast_celtic_cross(question="What should I focus on?", seed="user-42")
# Three-card past-present-future. Most-drawn spread on every tarot platform.
three = roxy.tarot.cast_three_card(question="My next quarter", seed="user-42")
# Yes / No. Impulse micro-query, highest conversion-to-first-call on tarot surfaces.
answer = roxy.tarot.cast_yes_no(question="Should I take the offer?")
# answer["answer"] ("Yes" | "No" | "Maybe"), answer["strength"]The breakout 2026 spiritual category, computed from the same ephemeris as Western astrology plus the I Ching gate wheel and chakra-style centers. Self-discovery apps, dating and compatibility products, and AI coaching bots are the buyers. The full bodygraph is the chart, returned in one call. No coordinates needed: Human Design uses the birth instant and ecliptic longitudes, so there is no city-search setup step.
# Full bodygraph. The #1 Human Design query, the whole chart in one call.
# `timezone` is the IANA string ("America/New_York"), same as the chart endpoints.
bodygraph = roxy.human_design.generate_bodygraph(
date="1990-07-04", time="10:12:00", timezone="America/New_York",
)
# bodygraph["type"] ("Generator", "Projector", "Manifestor", ...)
print(bodygraph["type"], bodygraph["strategy"], bodygraph["profile"], bodygraph["definition"])
# bodygraph["authority"], bodygraph["centers"], bodygraph["channels"], bodygraph["gates"]The first cross-domain, stateless forecast in the catalog. One call merges Western transit-to-natal aspects, sign ingresses, retrograde stations, Vedic Vimshottari dasha boundaries, and biorhythm critical days into a single significance-scored, time-ordered timeline. Forecast feeds, transit alerts, and timing tools are the buyers. The window is clamped to a 90-day horizon.
# Cross-domain timeline. Acquire on the transit keyword, convert on this breadth.
# Response keys are camelCase passthrough: result["count"], result["events"].
timeline = roxy.forecast.generate_timeline(
birth_data={
"date": "1990-07-04", "time": "10:12:00", "timezone": "America/New_York",
"latitude": 40.7128, "longitude": -74.006,
},
start_date="2026-06-01", end_date="2026-06-30",
)
print(timeline["count"]) # number of events in the window
event = timeline["events"][0]
print(event["date"], event["domain"], event["type"], event["description"], event["significance"])BaZi (Four Pillars of Destiny), the twelve-animal zodiac, and the lunisolar calendar with its almanac. The school splits that make two calculators disagree are typed request parameters with named defaults, echoed back in a conventions object on every response, so a chart can be reproduced rather than guessed at. The zodiac routes answer the high-volume consumer questions; BaZi and the almanac are where an app goes deeper.
# BaZi Four Pillars. The anchor call: the rest of the domain reads off these four pillars.
# `timezone` takes the IANA name, resolved to the DST-correct offset for the birth date.
bazi = roxy.chinese_astrology.generate_bazi_chart(
date="1990-07-04", time="10:12:00", timezone="America/New_York",
)
# bazi["pillars"][n]["position"] ("year" | "month" | "day" | "hour")
# ...["stem"]["element"], ["branch"]["animal"], ["tenGod"]["name"], ["hiddenStems"], ["naYin"]
print(bazi["dayMaster"]["element"], bazi["zodiacAnimal"])
# bazi["fiveElements"], bazi["conventions"], bazi["summary"]
# Chinese zodiac sign. Defaults `year_boundary` to "lunar-new-year", the folk rule people mean
# when they say which animal they are. Pass "li-chun" to match the classical BaZi boundary.
sign = roxy.chinese_astrology.calculate_zodiac_animal(date="1990-07-04")
# sign["animal"]["name"] ("Horse"), ["element"] ("Fire"), ["polarity"]
# sign["element"] is the YEAR STEM element ("Metal"), not the element of the animal.
# sign["yearPillar"], sign["interpretation"]Kua numbers with the full Eight Mansions map ranked best to worst, Xuan Kong flying star natal charts for any of the nine periods and 24 mountains, annual and monthly star plates, and the four annual afflictions with exact degree spans. Chinese years resolve at Li Chun, computed astronomically rather than assumed, so the annual charts change over on the real boundary.
# Kua number: one birth date and a gender gives the personal directions everything else reads off.
kua = roxy.feng_shui.calculate_kua_number(date="1990-07-04", gender="female")
print(kua["kua"], kua["group"], kua["trigram"]["english"]) # 8 west Mountain
# kua["sectors"][n]["direction"], ["starName"], ["nature"] ("auspicious" | "inauspicious"),
# ["rank"], ["domain"]
# 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 `facing_degrees`, not neither.
chart = roxy.feng_shui.generate_flying_star_chart(period=9, facing="S2")
# chart["facing"]["label"] ("S2"), chart["sitting"]["label"], chart["structure"]["name"]
# chart["palaces"][n]["palace"], ["base"], ["mountain"], ["water"], ["reading"]
# chart["mountainCenterStar"], chart["waterCenterStar"], chart["straddling"]Zero competition domain. Steady search volume with the top Google result being a static calculator page. Pure land-grab for wellness, productivity, sports, and couples apps.
# Daily biorhythm. Physical, emotional, intellectual, intuitive, plus seven extended cycles.
bio = roxy.biorhythm.get_daily_biorhythm(seed="user-1", date="2026-04-23")
# Multi-day forecast. Best-day / worst-day planner for calendar and coaching products.
forecast = roxy.biorhythm.get_forecast(
birth_date="1990-01-15", start_date="2026-04-01", end_date="2026-04-30",
)Meditation apps, decision-making tools, and wisdom chatbots. i ching API and hexagram API are the keywords.
# Cast a reading. Active divination, primary hexagram plus changing lines and transformed hexagram.
reading = roxy.iching.cast_reading(seed="user-42")
# reading["hexagram"], reading["changingLinePositions"], reading["resultingHexagram"]
# Hexagram catalog. Cache once for all 64 hexagrams.
hexagrams = roxy.iching.list_hexagrams()
# hexagrams["hexagrams"] has 64 entriesCrystal retail and metaphysical shops use these to build "crystals for [sign]" and "[chakra] chakra stones" pages.
# By zodiac. Highest-search crystal query pattern.
by_sign = roxy.crystals.get_crystals_by_zodiac(sign="scorpio")
# by_sign["crystals"] is a list of id, name, color, chakra, properties
# By chakra. Second-highest crystal query pattern.
by_chakra = roxy.crystals.get_crystals_by_chakra(chakra="heart")
# Birthstone. Evergreen gift and jewelry SEO.
birthstone = roxy.crystals.get_birthstones(month="4")Thousands of dream symbols. dream meaning is among the highest-volume spiritual searches on Google. Journal apps, AI therapy chatbots, and self-discovery products are the buyers.
# Symbol detail. Every "what does it mean to dream about X" page lands here.
symbol = roxy.dreams.get_dream_symbol(id="flying")
# symbol["id"], symbol["name"], symbol["meaning"]
# Symbol search. Chatbots cache the dictionary locally after one call.
results = roxy.dreams.search_dream_symbols(q="flying")
# results["symbols"] is an array of matching symbolsGen Z spiritual-tok fuel. 111 meaning, 222 meaning, 333 angel number are evergreen viral queries with massive shareability.
# By number. Every "meaning of 1111" page is backed by this.
angel = roxy.angel_numbers.get_angel_number(number="1111")
# angel["meaning"]["spiritual"], angel["meaning"]["love"], angel["affirmation"]
# Universal lookup. Works for any positive integer via digit-root fallback.
any_number = roxy.angel_numbers.analyze_number_sequence(number="4242")
This package ships AGENTS.md bundled alongside the source so AI coding agents can read the SDK patterns, common tasks, and gotchas directly from site-packages/.
Prefer MCP? Every domain has a remote MCP server at https://roxyapi.com/mcp/{domain} (Streamable HTTP, no stdio, no self-hosting). One-line Claude Code setup:
claude mcp add-json --scope user roxy-astrology \
'{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'Every method has an _async suffix variant for use with asyncio:
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())Interpretations and editorial text are available in 10 languages: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Pass lang as a keyword argument on any supported method. Defaults to en. Supported: astrology, vedic_astrology, forecast, human_design, chinese_astrology, feng_shui, mesoamerican_astrology, vastu, numerology, kabbalah, tarot, biorhythm, ayurveda, iching, crystals, angel_numbers, languages. English-only: dreams, location, usage. Languages without translations yet fall back to English.
card = roxy.tarot.get_daily_card(date="2026-04-22", lang="es")
life_path = roxy.numerology.calculate_life_path(year=1990, month=1, day=15, lang="hi")The two Chinese scripts (zh-Hans, zh-Hant) currently ship on Chinese astrology and feng shui; every other domain answers those codes in English per field.
The SDK is framework-agnostic. Works with Django, Flask, FastAPI, or any Python project.
from fastapi import FastAPI
from roxy_sdk import create_roxy
app = FastAPI()
roxy = create_roxy("your-api-key")
@app.get("/horoscope/{sign}")
async def horoscope(sign: str):
return await roxy.astrology.get_daily_horoscope_async(sign=sign)from flask import Flask, jsonify
from roxy_sdk import create_roxy
app = Flask(__name__)
roxy = create_roxy("your-api-key")
@app.route("/horoscope/<sign>")
def horoscope(sign):
return jsonify(roxy.astrology.get_daily_horoscope(sign=sign))from django.http import JsonResponse
from roxy_sdk import create_roxy
roxy = create_roxy("your-api-key")
def horoscope(request, sign):
return JsonResponse(roxy.astrology.get_daily_horoscope(sign=sign))All API errors raise RoxyAPIError with error (human-readable message), code (machine-readable, stable), and status_code attributes:
from roxy_sdk import create_roxy, RoxyAPIError
roxy = create_roxy("your-api-key")
try:
result = roxy.astrology.get_daily_horoscope(sign="invalid")
except RoxyAPIError as e:
print(f"Code: {e.code}")
print(f"Error: {e.error}")
print(f"Status: {e.status_code}")| Status | Code | When |
|---|---|---|
| 400 | validation_error |
Missing or invalid parameters |
| 401 | api_key_required |
No API key provided |
| 401 | invalid_api_key |
Key format invalid or tampered |
| 401 | subscription_not_found |
Key references non-existent subscription |
| 401 | subscription_inactive |
Subscription cancelled, expired, or suspended |
| 404 | not_found |
Resource not found |
| 429 | rate_limit_exceeded |
Monthly quota reached |
| 500 | internal_error |
Server error |
Switch on code, not error. Messages may be reworded; codes are stable.
Store your API key in an environment variable for production:
import os
from roxy_sdk import create_roxy
roxy = create_roxy(os.environ["ROXY_API_KEY"])Never expose your API key client-side. Call Roxy from server code only.
create_roxy accepts optional parameters for advanced usage:
roxy = create_roxy(
api_key="your-api-key",
base_url="https://roxyapi.com/api/v2", # default
timeout=30.0, # request timeout in seconds
)The client reuses HTTP connections. For explicit cleanup, use the context manager:
with create_roxy("your-api-key") as roxy:
horoscope = roxy.astrology.get_daily_horoscope(sign="aries")
# connections closed automatically