Natal charts, transits and synastry over a single JSON endpoint — computed by our own ephemeris engine. No licence fees passed on to you, and far more depth than a sun-sign lookup.
Most astrology APIs stop at planets in signs. Ours returns the layer underneath — the one serious astrologers build on.
We wrote the engine ourselves rather than wrapping a licensed one. That means no third-party licence fees baked into your bill, and no surprise upstream rate limits between you and your users.
Essential dignities, declinations, out-of-bounds planets, antiscia and contra-antiscia, midpoints and activations, chart patterns, royal stars and the Part of Fortune — returned by default, not sold as add-ons.
Pass a birth date, a local time and an IANA timezone. We resolve historical offsets and DST correctly — the single most common source of wrong charts in other APIs.
This is the same API that renders charts inside Caldera Astro and our free birth chart calculator. It is not a side project — it ships to real users every day.
Authenticate with an X-API-Key header. Everything is a plain GET with query parameters — no SDK required.
/v1/natal
A complete natal chart: ten planets with sign, degree, house, retrograde state and dignity; the lunar nodes, Chiron, Lilith and Part of Fortune; house cusps with ascendant and midheaven; aspects with orb and applying/separating; moon phase and illumination; plus midpoints, patterns, antiscia contacts and declination aspects.
/v1/transits
Current or dated transits against a natal chart. Returns transiting planets and points, the natal chart they are hitting, and every transit-to-natal aspect with its orb — ready for a "what's happening today" feed or a push notification.
/v1/synastry
Compatibility between two charts. Returns both charts side by side plus every inter-chart aspect with orb and nature — the backbone of any matching, dating or relationship feature.
No SDK, no OAuth dance, no chart-ID round trip. Send the birth data, get the chart.
curl "https://caldera-api-4owgwzlpaa-ey.a.run.app/v1/natal\
?date=1990-05-15\
&time=14:30\
&timezone=Europe/Istanbul\
&lat=41.0082\
&lon=28.9784\
&house_system=whole_sign" \
-H "X-API-Key: YOUR_API_KEY"{
"sun_sign": "Taurus",
"moon_sign": "Sagittarius",
"rising_sign": "Virgo",
"planets": [
{
"planet": "Sun",
"sign": "Taurus",
"degree_string": "24°22′",
"longitude": 54.376,
"house": 9,
"is_retrograde": false,
"dignity": { "name": "Peregrine" },
"declination": 18.8658,
"out_of_bounds": false
}, … 9 more
],
"houses": { "system", "ascendant", "midheaven", "cusps" },
"aspects": [ /* 18 aspects with orb */ ],
"moon_phase", "patterns", "midpoints", "royal_stars"
}Because we own the engine, we don't pay a per-call toll upstream — and we don't pass one on to you.
We're in early access, so keys are issued by hand — email us and we'll set you up, usually the same day. Self-serve billing is coming; until then there is nothing to cancel and no card on file.
Whole sign, equal and Placidus. Pass house_system=whole_sign, equal or placidus. Whole sign is the default, matching the tradition Caldera Astro is built on.
Send the date without a time and we default to noon local time. The response includes a has_time flag so you can hide houses, the ascendant and the midheaven in your UI when the time is unknown, rather than showing figures you can't stand behind.
You pass an IANA timezone such as Europe/Istanbul together with the local wall-clock time, and we resolve the correct historical UTC offset, including daylight saving. This is where most astrology APIs quietly get charts wrong.
Yes. A natal chart is deterministic — the same input always returns the same chart — so caching it against your user record is both allowed and encouraged. It also keeps your request count low.
The API returns computed astronomy and chart structure, not written interpretation. Hand-written readings are something we do inside Caldera Astro. If you need interpretation text for your product, talk to us about Enterprise.
Yes, per plan, and it's there to keep the service fast for everyone rather than to upsell you. If you're doing a large one-off backfill, tell us and we'll lift it for the window you need.
Tell us what you're building and we'll send a key. Free tier, no card, no sales call.