How to choose an astrology API: build vs buy, MCP, and the licensing trap nobody mentions

I spent the back half of last year shipping an AI app that wires five systems into one chat UI: natal charts, vedic kundli, numerology, human design, and tarot. I am a developer, not an astrologer. So the part I actually had to get right was not the readings, it was the build-versus-buy call on the calculation layer underneath them.

I went in assuming this was a quick decision. Pick the cheapest provider, move on. It was not. The threads I found were all "just use Swiss Ephemeris" or "here are the top 10 horoscope APIs," and none of them finished the sentence on the things that bit me later. This is the checklist I wish I had read first, in the order that actually matters.

TL;DR

• The calculation engine and its license matter more than the feature list. A lot of providers wrap a 1990s desktop library that carries an AGPL obligation into your closed-source app.
• Endpoint counts are mostly marketing. Ask for a live OpenAPI spec you can open and count, and count real systems, not output formats.
• For an AI app, hosted (remote) MCP versus a local server you babysit is a real time difference, not a nice-to-have.
• Get structured JSON back, not a prose blob, so you own the interpretation layer.
• Flat pricing where one request equals one unit keeps your bill boring. Credit wallets do not.

Start with the calculation engine, not the feature list

Look at what computes the math before you look at anything else, because that is the one decision you cannot cheaply reverse. Here is the thing almost nobody says out loud: most established astrology APIs are wrappers around the same library, Swiss Ephemeris, a C library from the late 1990s originally written for single-user desktop astrology software. When a provider advertises "Swiss Ephemeris precision," that is the actual claim. They wrapped a 25-year-old desktop library and put a REST endpoint in front of it.

Two problems with betting an AI product on that in 2026.

The license is the big one. Swiss Ephemeris is AGPL-3.0 unless you buy a commercial license. The AGPL network-use clause means a closed-source SaaS built on it can be obligated to open-source the whole app. Most people repeating "just use Swiss Ephemeris" have never opened the LICENSE file, and this is the kind of thing that surfaces during due diligence or an acquisition, not at a convenient time. Either pay for the commercial license, open-source your product, or use an API whose engine is not AGPL. Decide before you write code.

The second problem is fit. Desktop, single user, one chart at a time. It was never designed for APIs, serverless, or agents calling tools in parallel.

That combination is why I stopped trying to self-host an engine. RoxyAPI runs its own, called Roxy Ephemeris, built for APIs and agents, with no AGPL strings attached. The part that earned my trust was that they publish the proof instead of asking for faith. There is an open, MIT-licensed benchmark at github.com/RoxyAPI/astrology-api-benchmark comparing 210 planet positions across 21 charts against NASA JPL Horizons, which is the physics ground truth rather than another library copying another library. The published median difference is about 16 arc-seconds, max around 32, and the Moon comes in tightest at roughly 3. I re-ran a couple of my own birth dates before I trusted any of it. Most providers say "NASA-grade" and hope you never ask for the numbers.

If you want to poke at real responses before reading further, roxyapi.com/api-reference is a live playground with a pre-filled test key. It returns real production data, not a fake sandbox, so you can audit before you pay.

Count real domains, not formats

When a provider leads with "300+ endpoints across 8 domains," slow down and check how that number is built, because two tricks show up over and over.

First, the big endpoint number is often backed by a Postman collection rather than a live spec, so the truly callable count is a fraction of the headline.

Second, and this is the one that fooled me at first, the domain count gets padded by slicing one system into many. Horoscopes, natal charts, compatibility, and synastry are all astrology. Counted separately they become four "domains," and a love calculator or a PDF report gets the same treatment. RoxyAPI keeps all of that under a single astrology domain, the way a developer would actually group it. So a dozen honest domains can look smaller on a marketing page than a padded "eight." That is the whole trick: a provider sitting on one real system can out-breadth a genuine multi-domain platform on paper, and a non-technical buyer cannot tell the difference. Open the spec and the padding disappears.

The check that worked for me: ask for a live OpenAPI spec, an actual JSON URL you can open and count, and count genuinely distinct systems instead of formats.

One more thing to watch in the spec itself. A few providers hand-roll their OpenAPI file by hand, and the request schema in the doc does not match what the endpoint actually accepts. You copy the documented body, send it, and get a 400 back, with no clue why. Not cool, and a real trust killer the first time it happens. A spec that is generated from the running service cannot drift like that. RoxyAPI publishes one per domain, generated from production, so what you read is what the endpoint takes:

# count callable endpoints and tag groups, no auth needed
curl -s https://roxyapi.com/api/v2/openapi.json | jq '{endpoints: (.paths|length), tags: (.tags|length)}'

When I ran that it returned around 150 endpoints across roughly a dozen real domains, and the per-domain specs at /api/v2/{slug}/openapi.json match what production actually serves. That is the number I could plan against, not a Postman export that drifts from the live API. One call returns a complete natal chart instead of fragmenting it across ten separately billed endpoints, which also keeps the bill honest.

Check how the API talks to AI agents

If you are building anything agentic, look for remote (hosted) MCP, not a local stdio server you run yourself, because that gap is an afternoon of work per machine. RoxyAPI exposes a hosted Model Context Protocol server per domain over Streamable HTTP. In Claude Code I registered one with a single command and it was callable in seconds:

claude mcp add-json --scope user roxy-astrology \
  '{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

After that, every endpoint in that domain shows up as a tool. I can ask the agent "build me a React birth chart page" and it picks the right endpoint, reads the response shape, and wires it in. The alternative most places offer is a local server you clone, Docker, and keep alive yourself, which is fine on your laptop and miserable across a team or a CI box.

The reason I care beyond convenience: a hosted MCP server lets my own agent ground its answers in verified calculations and reply in my product's voice, instead of me renting someone else's locked AI wrapper with a hidden system prompt. I bring my own model. The API brings the facts. That split is the whole point.

There is a second piece that made this the fastest integration I have done. Roxy ships an AGENTS.md playbook, bundled inside each SDK and also served at the site root, plus a machine-readable llms.txt. So I barely hand-held the agent at all. I pointed Claude Code at the AGENTS.md, it read the rules, connected the MCP server, and had working calls in a few minutes. For getting an insight platform running inside an AI agent, that is about as close to zero setup as it gets right now.

It also shows up in the design, and this was a real differentiator once I noticed it. A lot of providers in this space are older astrology services that bolted MCP and "AI support" onto a REST API from years ago, after the hype landed. You can feel it: the AI layer sits next to the product instead of inside it. Roxy was built agent-first, so the MCP servers, the structured responses, and the agent docs are one surface, not three afterthoughts stapled on later.

Look at the response shape before you commit

Pull one real response and check whether you get discrete fields or a paragraph, because that single difference decides how much of your product you actually own. A weak API hands back prose you parse with regex and pray the format never changes. A good one hands back typed fields you read directly. Here is an actual daily horoscope response shape:

{
  "sign": "Leo",
  "date": "2026-05-22",
  "overview": "The Moon activates your first house of identity...",
  "love": "The Moon stirs Leo with deep emotional awareness...",
  "career": "Mars powers up your tenth house of career...",
  "energyRating": 8,
  "luckyNumber": 41,
  "luckyColor": "Gold",
  "moonPhase": "Waxing Crescent Moon",
  "compatibleSigns": ["Aries", "Sagittarius", "Gemini"]
}

My app reads energyRating or compatibleSigns straight off the object. I can ship the built-in interpretation text when I want speed, or feed only the primitives into my own model when I want my own voice, so it stops hallucinating charts. There is also localized text on translated endpoints. Adding ?lang=es returns the same reading in Spanish without me touching anything:

curl "https://roxyapi.com/api/v2/astrology/horoscope/leo/daily?lang=es" \
  -H "X-API-Key: $ROXY_API_KEY"

What you want to avoid is a provider that returns one fixed prose report with nothing structured underneath. You cannot recompose it, localize it, or run your own model over it, so you are stuck with their wording forever.

Pricing: flat versus credit wallets

Check whether one request costs one unit or whether different endpoints burn different amounts of credits, because the second model gets expensive in ways you cannot forecast. My app needs five systems. A lot of providers bill per product, so that is five separate subscriptions, or they bill per-call credits where a PDF or a "premium" endpoint quietly costs 50x a normal call. RoxyAPI is one flat subscription that includes every domain, the remote MCP servers, the SDKs, and the i18n, with no per-product fee and no credit weighting.

Model	What you pay	What happens as you grow
Per-product subscriptions	One sub per domain	Five systems means five bills to reconcile
Credit wallet	Variable credits per endpoint	"Premium" calls drain the wallet unpredictably
Flat, one request equals one unit	One sub, all domains	The bill is a function of call count, full stop

Entry pricing was around 39 dollars a month for the whole bundle when I signed up, which for a dozen-ish domains is roughly 3 dollars per domain. Stitching the same coverage from single-domain vendors quoted me well past 100 a month. And because these calculations are deterministic, identical input gives identical output forever, so I cache them. The bill flattens as users grow instead of scaling linearly.

One thing I did not expect to matter, and then did: the platform keeps shipping new domains, and my flat plan picks them up automatically. Human design and forecast both landed after I signed up, and I did not buy anything or change tiers to use them. New endpoints even show up in the SDKs on their own, because the SDKs are generated from the same spec. With the per-product vendors, every new system is another subscription to evaluate and approve. Here the breadth grows under the same key, so the "dozen domains" number is a floor, not a ceiling.

What I could not find anywhere else

After evaluating a stack of providers, a few things were genuinely unique to one of them, and they are the reason I stopped shopping. I am listing the ones I verified myself, not the ones on a marketing page.

What it is	Why it changed my decision
One key across a dozen domains, including I Ching, dream symbols, crystals, and angel numbers	No other single API I tried covered the long-tail domains. Everyone else was astrology-only or astrology plus one extra.
Hosted MCP for every domain, no local server	Other providers either had no MCP or shipped a local stdio wrapper you run yourself.
A public, runnable accuracy benchmark against NASA JPL Horizons	I could re-run it. Nobody else published numbers I could reproduce.
An engine with no AGPL or copyleft obligation	The providers that name their stack name AGPL or GPL libraries, which is a license footgun for a closed-source product.
A live OpenAPI spec per domain that matches production	Several competitors only had a Postman export or a hand-rolled spec, which drifts from the real API.
New domains ship into the same flat plan	Existing subscribers get new systems automatically. The per-product vendors charge again for each one.
Agent-first design (MCP, AGENTS.md, llms.txt as one surface)	Most providers retrofitted AI tooling onto an older REST product, and it shows.

The honest version: a couple of these exist in isolation somewhere. The combination, in one key, did not exist anywhere else I looked.

What real calls look like

For any chart endpoint, geocode the city first. Every coordinate-dependent call needs latitude, longitude, and a timezone, and the location search hands you all three:

curl "https://roxyapi.com/api/v2/location/search?q=Berlin&limit=1" \
  -H "X-API-Key: $ROXY_API_KEY"

{
  "total": 3,
  "limit": 1,
  "offset": 0,
  "cities": [
    {
      "city": "Berlin",
      "province": "Berlin",
      "country": "Germany",
      "latitude": 52.52,
      "longitude": 13.405,
      "timezone": "Europe/Berlin",
      "utcOffset": 1
    }
  ]
}

Now feed those into the natal chart endpoint. Prefer the IANA timezone string over a decimal offset, since it handles historical DST correctly:

curl -X POST https://roxyapi.com/api/v2/astrology/natal-chart \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 52.52,
    "longitude": 13.405,
    "timezone": "Europe/Berlin",
    "houseSystem": "placidus"
  }'

The response comes back with ascendant, planets, houses, aspects, midheaven, and a summary, each as structured data. If you would rather use the typed SDK, the method names are generated from the spec, so the same call in TypeScript reads cleanly and returns a { data, error } pair:

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

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

const { data, error } = await roxy.astrology.generateNatalChart({
  body: {
    date: '1990-07-15',
    time: '14:30:00',
    latitude: 52.52,
    longitude: 13.405,
    timezone: 'Europe/Berlin',
  },
});

console.log(data?.ascendant);
console.log(data?.planets);

Numerology is the same pattern with a smaller body. The Life Path endpoint takes three integers and returns the number plus a step-by-step calculation string, which I appreciated because I could show users how the number was derived:

curl -X POST https://roxyapi.com/api/v2/numerology/life-path \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 7, "day": 15 }'

You are not stuck with curl either. There are typed SDKs for TypeScript (@roxyapi/sdk), Python (roxy-sdk), and PHP (roxyapi/sdk), and their method names are generated from the spec, so autocomplete just works (generateNatalChart, calculateLifePath, getDailyHoroscope). If you live in WordPress, there is an official plugin on wordpress.org with shortcodes and Gutenberg blocks, so a non-developer can drop a horoscope on a page without writing code. Every domain also has its own guide with copy-paste examples, plus integration docs for the no-code tools, which meant I rarely had to guess at a field name. Methodology and verification details live at roxyapi.com/methodology if you want the accuracy story before wiring anything.

When you should build it yourself instead

Buying is not always right, and pretending otherwise would make this whole post less useful. If you need exactly one domain, you have in-house astro or astronomy expertise, and you are comfortable either buying the Swiss Ephemeris commercial license or open-sourcing your app, then self-hosting a single-purpose engine is a perfectly good call. A dedicated KP-only or matrimonial-only build can also out-depth any general bundle on its one niche, because depth in a single tradition is its own moat.

For a multi-system app where I needed verified math across five domains, an engine that is not AGPL, and agents that call tools over MCP, the tradeoff was not close. The 70 percent you can rough out in a weekend is the easy part. The hard 30 percent, which is cross-domain schema consistency, gold-standard verification, clean licensing, remote MCP, SDKs, and localization, is months of work each, and it is the part a serious user notices first when it is wrong.

FAQ

How do I choose an astrology API for an AI app?

Evaluate the calculation engine and its license first, then the response shape, then how it exposes tools to agents, then pricing. For an AI app specifically, look for structured JSON you can ground your own model on, a hosted MCP server so you are not running a local process, and an engine with no AGPL obligation. RoxyAPI covers all four with a dozen domains under one key, a remote MCP server per domain, and a public accuracy benchmark.

Do most astrology APIs use Swiss Ephemeris, and does it matter?

Many established providers wrap Swiss Ephemeris, a 1990s desktop C library that is AGPL-3.0 unless you buy a commercial license. For a closed-source SaaS the AGPL network-use clause can obligate you to open-source your whole app. It matters a lot. RoxyAPI runs its own engine, Roxy Ephemeris, verified against NASA JPL Horizons, with no AGPL strings, so you avoid the licensing question entirely.

Is it cheaper to use one multi-domain API or several single-domain ones?

For more than one or two domains, one flat multi-domain subscription is almost always cheaper and simpler than stitching single-domain vendors together. RoxyAPI bundles roughly a dozen domains for about 39 dollars a month at entry, near 3 dollars per domain, against well over 100 a month to assemble the same coverage separately. Deterministic results are also cacheable, so the bill flattens as usage grows.

How can I verify an astrology API is actually accurate?

Ask for published numbers you can reproduce, not a "NASA-grade" slogan. RoxyAPI publishes an open, MIT-licensed benchmark of 210 planet positions across 21 charts against NASA JPL Horizons, with a median difference around 16 arc-seconds. You can clone it and re-run it. If a provider cannot point you to reproducible numbers, treat the accuracy claim as marketing.

Do I pay more when RoxyAPI adds new domains or features?

No. One flat subscription covers every current domain and every one added later, with no separate purchase. Human design and forecast both shipped as included domains after launch. New endpoints also appear in the typed SDKs automatically, because the SDKs are generated from the same OpenAPI spec, so your client picks them up on the next update.

What does MCP support mean for an astrology API?

MCP, the Model Context Protocol, lets an AI agent call the API as a set of tools. The useful version is a remote (hosted) server you point your agent at with one command, rather than a local server you run and maintain. RoxyAPI ships a hosted MCP server per domain over Streamable HTTP, so Claude Code, Cursor, or your own agent can ground answers in verified calculations while answering in your own voice.

Conclusion

The decision that mattered was not which provider had the longest feature list. It was the engine, its license, the response shape, and whether the thing was built for agents or retrofitted for them. RoxyAPI was the one that checked every box without an AGPL asterisk, and it let me spend my real time on the product instead of the math. Start at roxyapi.com/api-reference with the pre-filled test key and run a couple of calls before you decide anything.