Skip to content

README.md

Latest commit

 

History

History
221 lines (159 loc) · 6.37 KB

README.md

File metadata and controls

221 lines (159 loc) · 6.37 KB

roxy-sdk

PyPI Python Docs API Reference License

Python SDK for RoxyAPI. Astrology, tarot, numerology, I Ching, crystals, angel numbers, dream interpretation, and more. One API key, 10 domains, 120+ endpoints.

Install

pip install roxy-sdk

Quickstart

from roxy_sdk import create_roxy

roxy = create_roxy("your-api-key")
horoscope = roxy.astrology.get_daily_horoscope(sign="aries")
print(horoscope)

Get your API key at roxyapi.com/pricing. Free test keys available on the interactive docs.

Recipes

Dating app: zodiac compatibility

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}

score = roxy.astrology.calculate_compatibility(person1=person1, person2=person2)
print(f"Compatibility: {score}")

Wellness app: daily tarot card

card = roxy.tarot.get_daily_card()
print(f"Today: {card}")

Journaling app: dream interpretation

symbol = roxy.dreams.get_dream_symbol(id="flying")
print(f"Flying in dreams: {symbol}")

Numerology calculator: life path number

result = roxy.numerology.calculate_life_path(year=1990, month=1, day=15)
print(f"Life Path: {result}")

chart = roxy.numerology.generate_numerology_chart(full_name="Jane Smith", year=1990, month=1, day=15)
print(f"Full chart: {chart}")

Crystal healing: zodiac crystals

crystals = roxy.crystals.get_crystals_by_zodiac(sign="scorpio")
print(f"Scorpio crystals: {crystals}")

I Ching: daily reading

reading = roxy.iching.cast_daily_reading()
print(f"I Ching: {reading}")

Domain reference

Domain Property What it covers
Western Astrology roxy.astrology Natal charts, horoscopes, synastry, compatibility, transits, moon phases
Vedic Astrology roxy.vedic_astrology Birth charts, dashas, nakshatras, panchang, KP system, doshas, yogas
Tarot roxy.tarot Spreads, daily pulls, yes/no oracle, Celtic Cross, custom layouts
Numerology roxy.numerology Life path, expression, soul urge, personal year, karmic analysis
I Ching roxy.iching Hexagrams, trigrams, coin casting, daily readings
Crystals roxy.crystals Healing properties, zodiac/chakra pairings, birthstones, search
Angel Numbers roxy.angel_numbers Number meanings, pattern analysis, daily guidance
Dreams roxy.dreams Symbol dictionary, interpretations, daily guidance
Location roxy.location City geocoding for birth chart coordinates
Usage roxy.usage API usage stats and subscription info

Async support

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())

Framework examples

The SDK is framework-agnostic. It works with Django, Flask, FastAPI, or any Python project.

FastAPI

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)

Flask

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))

Django (views.py)

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))

Error handling

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"Error: {e.error}")
    print(f"Code: {e.code}")
    print(f"Status: {e.status_code}")

Error codes:

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
429 rate_limit_exceeded Monthly quota reached
404 not_found Resource not found
500 internal_error Server error

Environment variable

Store your API key in an environment variable for production use:

import os
from roxy_sdk import create_roxy

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

Configuration

create_roxy accepts optional parameters for advanced usage:

roxy = create_roxy(
    api_key="your-api-key",
    base_url="https://roxyapi.com/api/v2",  # default, override for local development
    timeout=30.0,                            # request timeout in seconds (default: 30)
)

The client reuses HTTP connections for performance. 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

Links