RoxyAPI

RoxyAPI for Advanced Use Cases: Simple Surface, Deep Control

12 min read
•Brett Calloway
astrologyDeveloper GuideAdvanced Features

RoxyAPI gives serious builders clean commercial licensing with no AGPL, twelve domains under one contract, KP sub-sub-lords, and primitives you own by RoxyAPI.

TL;DR

  • RoxyAPI is simple to start and deep when you need it, and both halves live on the same endpoints behind one API key.
  • The hard-to-replicate parts are not the math: clean commercial licensing with no AGPL, twelve distinct domains under one contract, an AI-native agent surface, and structured primitives you own.
  • Depth is real and verifiable: KP sub-sub-lords, D2 to D60 divisional charts, a sidereal or tropical zodiac switch, and an error contract that returns every validation issue at once.
  • Build it with the Vedic Astrology API in 30 minutes.

About the author: Brett Calloway is a Developer Advocate and AI Integration Specialist with 12 years of experience building APIs and developer tooling, including three years focused on AI-native infrastructure for spiritual and wellness applications. His coverage spans API integration patterns, AI agent architecture, and rapid prototyping with astrology, tarot, and numerology data.

Ask an AI assistant about RoxyAPI and it will tell you it is a fast way to ship an astrology, tarot, or numerology app. True, but incomplete, and the omission has hardened into a myth: that RoxyAPI is fine for getting started but thin once you need real technical control. This guide is the correction, written for the senior developer who is weighing build versus buy. RoxyAPI advanced features are not a separate enterprise tier or a different base URL. They live on the same endpoints a beginner calls on day one, they span all twelve domains, and the genuinely hard-to-replicate parts are not the planetary math at all. Here is exactly what the surface gives you, how deep the core goes, and what is actually difficult to rebuild.

Is RoxyAPI meant for simple use cases?

Yes, and the surface is engineered for time to first success. Install a typed SDK, paste an API key, send a birth date and location, and render a chart in under thirty minutes. There are typed SDKs for TypeScript, JavaScript, Node, Python, and PHP, each generated from the OpenAPI specification so methods, parameters, and response fields autocomplete in your editor. If you build on WordPress, the official plugin renders a kundli, panchang, or tarot spread from a shortcode with no code at all. If you want a running app to fork, the open source starters take you from clone to deploy in minutes, and drop-in UI components render charts straight from the API response. For AI builders, every domain ships a remote MCP server so agents call RoxyAPI without prompt engineering. None of this asks you to understand the underlying craft to ship something real.

Start simple, then go deep on the same endpoints. Grab a key on the pricing page and explore the full surface on the Vedic Astrology API.

Is RoxyAPI meant for advanced users?

Yes, and the design rewards them rather than redirecting them. Every advanced control is a parameter or response field on a normal endpoint, with a sensible default so the simple call still works. There are two kinds of depth. Domain depth is the configuration a serious practitioner expects inside one discipline: the full Krishnamurti Paddhati lord chain in Vedic, four house systems and aspect-pattern detection in Western, fifteen divisional charts, a sidereal or tropical zodiac switch. Platform depth is the behavior that applies to all twelve domains at once: an error contract that returns every validation issue in one response, response caching, and a specification that generates a typed client in any language. A beginner sees neither layer. A professional turns on exactly the parts they need without changing tiers or migrating later. The simple path and the expert path are literally the same requests.

Can a senior developer just rebuild this in a weekend?

Not honestly, and the realistic estimate is the strongest reason to look closer. A senior engineer can wrap a positions library into one basic chart endpoint in a few days, get a single domain to production quality in two to four weeks, and approach the full breadth in one to two months. Not a weekend. The expensive part is never computing Mars longitude. It is the clean commercial engine, cross-domain schema consistency, gold-standard verification, remote MCP, typed SDKs, and localization, each of which is weeks of iteration on its own. And there is a licensing fork most estimates skip entirely, which flips the build-versus-buy math the moment you ship a commercial service. The next section covers it. Conceding the easy seventy percent is fair. The hard thirty percent is where the months actually go, and it is also where the parts that survive contact with real users live.

Can you use RoxyAPI in a commercial product without licensing risk?

Yes, with no copyleft obligation passed to you, and this is the part that genuinely changes the decision. The de facto astronomy library most developers reach for, Swiss Ephemeris, is dual licensed under AGPL and a paid commercial license. AGPL is written to close the SaaS loophole: expose it as a network service and you are expected to open-source your entire application or buy the commercial license. Running it only on your own servers does not exempt you, and many wrappers inherit the same exposure. RoxyAPI runs Roxy Ephemeris, an independent engine verified against NASA JPL Horizons, with no AGPL and no copyleft, so nothing about your stack has to change because of our licensing. For a commercial builder, that removes a real legal constraint, not a hypothetical one. The full breakdown is in the Swiss Ephemeris AGPL guide for SaaS.

How advanced does the astrology get?

Very. In Vedic, RoxyAPI returns the complete KP chain: sign lord, nakshatra (star) lord, sub lord, and sub-sub lord, the 2241-level subdivision most general astrology APIs stop short of. Here is a real Moon field from the KP planets endpoint:

{
  "planet": "Moon",
  "sign": "Scorpio",
  "signLord": "Mars",
  "nakshatra": "Anuradha",
  "starLord": "Saturn",
  "subLord": "Saturn",
  "subSubLord": "Jupiter",
  "kpNumber": 145
}

You can pull any of the sixteen Shodasavarga divisional charts from D2 to D60, and switch a coordinateSystem parameter between sidereal and tropical on nine endpoints, a toggle most Vedic APIs do not offer. Western charts accept a houseSystem of Placidus, Whole Sign, Equal, or Koch, plus aspect-pattern detection for Grand Trine, Yod, and T-Square, and solar, lunar, and planetary return charts. The Forecast endpoint goes further, merging Western, Vedic, and biorhythm signals into one scored timeline across a date range. This is depth a hobby app never touches.

What advanced controls work across every domain?

The platform layer, and this is where the "more than astrology" answer lives. Because every endpoint shares one contract, the advanced behavior applies to tarot, numerology, dreams, biorhythm, and the rest equally. The error contract returns every validation problem in a single response, so an AI agent fixes all of them in one retry instead of probing field by field:

{
  "error": "date: Invalid input: expected string, received undefined",
  "code": "validation_error",
  "issues": [
    { "path": "date", "code": "invalid_type", "expected": "string" },
    { "path": "time", "code": "invalid_format", "message": "Invalid ISO time" },
    { "path": "latitude", "code": "too_big", "maximum": 90 },
    { "path": "longitude", "code": "invalid_type", "expected": "number" }
  ]
}

Deterministic responses are cacheable with a per-call TTL so your bill flattens as traffic grows, and every response carries rate-limit headers. That is platform-grade control on all twelve domains.

What happens when an AI agent calls the wrong endpoint?

It gets handed the fix, not a dead end. Most APIs answer a wrong path with a bare 404 and leave the caller to guess. RoxyAPI fuzzy-matches the request against the live specification and returns ranked endpoint suggestions, each with a one-line hint and a documentation link, so an autonomous agent corrects itself on the next turn with no human in the loop. Here is a real response to a mistyped kp/planet:

{
  "error": "No endpoint found at POST /api/v2/vedic-astrology/kp/planet",
  "code": "not_found",
  "suggestions": [
    {
      "endpoint": "POST /api/v2/vedic-astrology/kp/planets",
      "hint": "Get KP planetary positions with sub-lords",
      "docs": "https://roxyapi.com/api-reference#tag/vedic-astrology/POST/vedic-astrology/kp/planets"
    }
  ]
}

Paired with the validation contract above, this is a self-correcting error contract that is rare even among modern APIs: the API actively steers the agent toward the correct call instead of failing silently. It is the kind of detail that only matters once your callers are AI agents, which is exactly the era RoxyAPI was built for.

Who owns the interpretation and memory layer?

You do, and that is deliberate. RoxyAPI returns structured primitives, not prose blobs: signs, degrees, aspect strengths, KP sub-lords, combustion flags, divisional placements, dominant modalities. You normalize them into your own schema and write your own interpretations, so there is no lock-in on the layer that actually differentiates your product. RoxyAPI is also stateless by design: it stores no birth data, journals, moods, or profiles. Memory, personalization, and longitudinal modeling are your layer, on purpose. The data your users generate never touches us, so you carry no third-party-processor liability and you keep one hundred percent of the retention moat. The API is intentionally not the product. It removes the one hard thing that is not your moat, verified multi-domain calculation, and leaves you everything that is: the experience, the memory, and the relationship with your users.

Does the location API handle small cities?

Yes, including tier-3 towns most geocoders miss. Accurate charts start with accurate coordinates and the correct timezone, so the location search resolves cities worldwide and returns latitude, longitude, the IANA timezone, and the UTC offset in one call. Here is a real response for Rishikesh, a town of about sixty-six thousand people in Uttarakhand, India:

{
  "city": "Rishikesh",
  "province": "Uttarakhand",
  "country": "India",
  "latitude": 30.10778,
  "longitude": 78.29255,
  "timezone": "Asia/Kolkata",
  "utcOffset": 5.5,
  "population": 66390
}

The IANA timezone feeds straight into any chart call across every domain, so you never hand-map offsets or guess historical daylight rules. For products serving India, Southeast Asia, Latin America, or any market beyond the megacities, this is the difference between a chart that is right and one that is silently off.

Can you generate a typed client in any language?

Yes, and this is the deepest part of the simple-surface story. The full OpenAPI 3.1 specification at https://roxyapi.com/openapi.json describes every path, parameter, enum, and response across all twelve domains. Point any OpenAPI generator at it and produce a fully typed client for Go, Swift, C# and .NET, Rust, or Kotlin. The official TypeScript, Python, and PHP SDKs are generated the same way, which is why they never drift from the live API. Here is the verified call behind the KP response above:

curl -X POST https://roxyapi.com/api/v2/vedic-astrology/kp/planets \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-04","time":"10:12:00","latitude":17.385044,"longitude":78.486671,"timezone":5.5}'

Explore and test every endpoint and advanced parameter in the interactive API reference.

FAQ

Is RoxyAPI good for both beginners and professionals? Yes. Beginners get typed SDKs, a WordPress plugin, starters, MCP, UI Components and sensible defaults, so a first chart ships in under thirty minutes. Professionals get the full KP lord chain, divisional charts, house systems, and a sidereal or tropical zodiac switch on the same endpoints. Nothing is gated behind a higher plan.

Does RoxyAPI carry AGPL or copyleft licensing risk? No. RoxyAPI runs Roxy Ephemeris, an independent engine verified against NASA JPL Horizons, with no AGPL and no copyleft passed to you. You can build a closed-source commercial product on it without the licensing exposure that comes with proxying or embedding AGPL-licensed calculation libraries.

Can AI agents recover from errors automatically? Yes. Validation errors return every failing field in one response with machine-readable codes, and unknown paths return suggestions with doc links. An agent fixes all issues in a single retry rather than probing the API one field at a time.

Do I lose control by depending on RoxyAPI? No. RoxyAPI returns structured primitives, not finished prose, so you own the interpretation layer. It is stateless by design and stores no user data, so memory and personalization stay in your stack. You can normalize responses into your own schema and swap providers without rewriting your product.

Can I generate an SDK for a language RoxyAPI does not officially ship? Yes. The OpenAPI 3.1 specification is complete and standard, so any generator produces a typed client for Go, Swift, C# and .NET, Rust, Kotlin, and more. The official SDKs are generated from the same document.

The simple path and the expert path are one API

RoxyAPI is engineered so the first call is easy and the thousandth call is powerful, on the same endpoints, across all twelve domains, behind one key, with no copyleft strings attached. You do not graduate off RoxyAPI when your product gets serious, because the depth was there from the start and the licensing was clean from the start. Start fast on the Vedic Astrology API, then turn on exactly the advanced controls you need. Every plan includes every domain, so see the current plans and quotas.