Astrology calculation engine, own your voice

RoxyAPI ships editorial interpretation text in 8 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 8 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:

{
  "sign": "Leo",
  "date": "2026-05-22",
  "overview": "The Moon activates your first house of identity and self-expression...",
  "love": "The Moon stirs Leo with deep emotional awareness...",
  "career": "Mars powers up your tenth house of career and ambition...",
  "energyRating": 8,
  "luckyNumber": 41,
  "luckyColor": "Gold",
  "moonPhase": "Waxing Crescent Moon",
  "moonSign": "Leo",
  "compatibleSigns": ["Aries", "Sagittarius", "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 8 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.

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 open-source 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.

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 },
  };
}

def to_reading(api: dict) -> dict:
    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 8 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:

{
  "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 8 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

Cut repeat calls with caching, add per-user memory in the AI companion tutorial, and browse the full surface in the product catalog.