Skip to content
RoxyAPI
Get API Key

Astrology calculator API with your own interpretations

RoxyAPI ships editorial interpretation text in 10+ languages and the structured data behind it. Launch instantly on our readings, then own the voice, personalization, and memory yourself when you want a product that is unmistakably yours. This is the architecture that keeps your switching cost low.

The most defensible way to build on any data API is to treat it as infrastructure you can shape, not a black box you reformat. RoxyAPI gives you both halves: editorial interpretation text on the common endpoints (in 10+ languages) so you can ship readings on day one, and the discrete structured fields behind every reading so you can build your own voice on top. You get the hard part for free and keep the part that actually differentiates your app.

Structured fields and ready interpretations

A weak API hands back one opaque paragraph you parse with regex and pray the format never changes. RoxyAPI returns discrete, documented fields you read directly, and where a reading makes sense it carries the prose as its own fields (interpretation.summary, interpretation.detailed) rather than one blob. A daily horoscope, for example, comes back as typed data:

json
{
  "sign": "Leo",
  "date": "2026-05-22",
  "overview": "Hope wakes up with the sunrise: your ruling Sun in your realm of friendship moves into conjunction with Uranus today, with a lively new current. Plus, the soulful Moon is in your realm of identity through May 23, bringing up a tender call for rest. Unease can creep in if plans shift at the last minute, yet a bit of flexibility goes far. If your focus feels scattered across too many places, let today be the day you choose one priority. The spark in you is still glowing.",
  "love": "A slow reply can send your thoughts spiraling into overthinking; still, patience usually pays off for you. Your zone of identity and presence hosts the nurturing Moon until May 23, gently stirring a fond hope for carefree affection. You crave feeling seen and valued since Venus in your solitude sector moves into square with compassionate Neptune today, with tension that builds strength. If keeping your guard up starts to feel tiring, why not drop the act, show more of yourself or lower the drawbridge? Passion and gentleness can share the same room.",
  "career": "Ideas flow with joyful energy as messenger Mercury in your friendship realm reaches a sextile with Saturn today: a promising path ahead. Limits on your hours may feel real once your travel realm holds mature Saturn. Preparation can give you a calm edge in demanding tasks, a head start you earned. Whenever teamwork runs a little less smoothly than usual, you could ask for input. Praise going to someone else can sting more than expected, but one honest talk can reset things. Patience can smooth even a rough patch.",
  "energyRating": 7,
  "luckyNumber": 1,
  "luckyColor": "Gold",
  "moonPhase": "Waxing Crescent Moon",
  "moonSign": "Leo",
  "compatibleSigns": [
    "Aries",
    "Aquarius",
    "Gemini"
  ]
}

Your app reads energyRating or compatibleSigns straight off the object. That structure is what lets you build your own experience on top instead of reformatting prose written by someone else.

Own your interpretation layer

We do the writing for you first: common endpoints (natal chart, numerology, tarot, biorhythm, I Ching, crystals, and more) ship editorial interpretation text in 10+ languages, so you launch without writing a word. When you want a voice that is unmistakably yours, take the same structured fields and run them through your own logic: your LLM prompts, your tone, your scoring, your recommendations. That upgrade is where retention lives, and because the structured data ships in every response you never have to choose up front.

Feed the structured fields to your LLM as grounded context, not the other way around. Let RoxyAPI decide the facts (positions, aspects, numbers) and let your model decide the voice. Deterministic grounding plus your prompt is what produces readings that feel personal without hallucinating the astrology. For a measured example of how far a free-hand model drifts, see why AI chatbots hallucinate birth charts.

A typical flow: call the chart or horoscope endpoint, cache the deterministic result (see caching), then synthesize the narrative your users see with your own model and brand voice.

For the visual half of the product, you do not need a frontend specialist who understands natal wheels or kundli layouts. The MIT licensed UI components render charts, kundli, panchang, human design, forecast, numerology, tarot, and biorhythm from the API response, so a designer with no insight-domain knowledge is no longer a blocker to shipping.

Normalize into your own schema

The single best defense against lock-in is an adapter. Map the API response into your own internal type the moment it arrives, and let the rest of your app depend on your type, never on the raw response shape.

ts
type Reading = {
  headline: string;
  energy: number;
  themes: { love: string; career: string };
};

function toReading(api: HoroscopeResponse): Reading {
  return {
    headline: api.overview,
    energy: api.energyRating,
    themes: { love: api.love, career: api.career },
  };
}

Now your components, prompts, and storage all speak Reading. If you ever change providers or add a second source, you rewrite one adapter, not your whole app.

Which fields are safe to key off

If you are building your own interpretation layer, the fields you branch on matter more than the prose you replace. The contract is simple and it holds across every domain.

Identifiers stay English in every language. A planet name, a sign, an aspect type, an aspect interpretation of harmonious or challenging or neutral, a dignity of domicile or exaltation: these are values your code compares, switches on, or uses as a lookup key, so they never change when you pass ?lang=. Write if (aspect.interpretation === 'challenging') once and it keeps working in all 10+ languages.

Display copy is translated in place. Anything a reader sees rather than your code reads (a description, a summary, keywords, a reference card) comes back in the language you asked for.

Where you need both, the display copy arrives as a sibling field, suffixed Localized, and it is absent when you request English so a plain call is byte-identical to one made before the field existed:

json
{
  "planet1": "Sun",
  "planet1Localized": "Sol",
  "type": "TRINE",
  "typeLocalized": "Trígono",
  "interpretation": "harmonious"
}

Read planet1Localized ?? planet1 when you print, and compare against planet1 when you branch. Never compare against the localized copy: it is the one field designed to change.

What the licence lets you do with the words

Replacing our interpretation text with your own is not a grey area, and neither is building on it.

  • Results are yours to use, including commercially. You do not owe us a share of what you build, and there is no per-seat or per-end-user fee on top of your plan.
  • Works you derive from results are yours. Translations, rewrites, adaptations, and text your own model produces from our structured fields belong to you. That survives cancellation, so a reading you generated while subscribed does not stop being yours when you stop paying.
  • What you may not do is resell the raw feed. Building your product on the data is the intended use; repackaging our responses as a competing data API is not.

The exact wording lives in the licence and in sections 2.3 to 2.5 and 5.2 to 5.4 of the terms. Read those two if you are writing anything contractual.

Keep user data on your side

RoxyAPI stores no end-user data. It computes from the inputs you send and returns a result; there is no profile, no history, no journal kept on our side. That is deliberate, and it works in your favor: your users data and the memory layer that personalizes their experience stay entirely yours, with no third-party processor in the path. To add per-user memory, see build an AI companion with memory.

FAQ

Will I be locked into RoxyAPI?

No more than you choose to be. Because responses are structured, you can normalize them into your own schema with a thin adapter, so your application logic never depends on the raw shape and switching cost stays low.

Should I use the API output directly or wrap it?

Wrap it. Map each response into your own internal type at the boundary so the rest of your app depends on your schema, not the provider format. This is the standard adapter pattern and it pays for itself the first time anything changes.

Do I have to write the interpretations myself?

No. Common endpoints return editorial interpretation text in 10+ languages, so you can launch on our readings immediately. When you want a distinct brand voice, layer your own prompts, tone, and scoring on the same structured fields. Both ship in every response, so it stays your call, not a limitation.

Can I rewrite the interpretations and still ship commercially?

Yes. Text you derive from a response is yours, including translations and anything your own model writes from the structured fields, and that stays true after you cancel. The one line you cannot cross is repackaging the raw responses as a competing data API. See the licence.

Does RoxyAPI keep my users data?

No. The API is stateless and stores no birth data, journals, or profiles. You keep all user state on your side, which keeps you in control of privacy and personalization.

Next steps

See how horoscopes are composed from real transits in the horoscope API JSON guide, cut repeat calls with caching, add per-user memory in the AI companion tutorial, and browse the full surface in the product catalog.