What the Astrologer API does and who it is for

The Astrologer API handles the heavy lifting of astrological computation — planetary positions, house systems, aspects, compatibility scores, and moon phases — and returns results either as production-ready SVG charts or as structured JSON, depending on which endpoint family you call. The calculations are described as NASA-grade in precision, rooted in the open-source Kerykeion library.

The API suits three broad audiences. First, developers building astrology apps or horoscope features who want to skip building their own ephemeris engine. Second, teams working on compatibility or dating platforms that need relationship analysis (synastry, composite charts, Ciro Discepolo scores). Third, AI/LLM application builders who need structured astrological context to feed into language models — the API has a dedicated set of context endpoints that return XML strings optimised for that exact purpose.

Authentication is handled via RapidAPI: every request carries X-RapidAPI-Key and X-RapidAPI-Host headers. There is no separate API key system to manage outside of your RapidAPI account.

Endpoint walkthrough

The API organises its surface into four endpoint families, all under /api/v5/.

Chart endpoints — SVG plus data

Seven POST endpoints return both a rendered SVG and the underlying astrological data in a single response:

  • /api/v5/chart/birth-chart — natal chart
  • /api/v5/chart/synastry — dual-wheel comparison of two subjects
  • /api/v5/chart/transit — current planets overlaid on a natal chart
  • /api/v5/chart/composite — midpoint chart representing a relationship as a third entity
  • /api/v5/chart/solar-return — annual forecast chart for the next solar return
  • /api/v5/chart/lunar-return — monthly forecast chart for the next lunar return
  • /api/v5/now/chart — chart for the current UTC moment at Greenwich

The SVG sits in a chart key of the JSON response by default. Adding "split_chart": true swaps that single key for chart_wheel and chart_grid — two separate SVGs representing the zodiac wheel and the aspect grid, respectively. This is useful when you want to animate or independently size the wheel versus the table, or position them differently in a layout. A transparent_background flag and multiple themes (classic/modern, light/dark) give you enough visual control to drop the output straight into most UIs without post-processing.

The subject object you pass must include year, month, day, hour, minute, longitude, latitude, and timezone. Two-subject endpoints (synastry, composite) accept first_subject and second_subject. Return chart endpoints additionally take a year integer to target a specific return.

Chart-data endpoints — JSON only

Mirror endpoints under /api/v5/chart-data/ return the same structured data (planetary positions, aspects, house distributions) without incurring the rendering cost of SVG generation. If you are building your own visualisation layer or feeding data into a database, these are the ones to reach for. There is also /api/v5/subject for a normalised subject object and /api/v5/compatibility-score for a standalone Ciro Discepolo compatibility score with a numerical result, a description, and a "destiny sign" flag.

Moon phase endpoints

Four dedicated endpoints handle lunar phase analysis with a simplified request model — no subject wrapper, just date/time and coordinates:

  • /api/v5/moon-phase — phase name, illumination, waxing/waning, moon age, upcoming major phases, next eclipses, sunrise/sunset
  • /api/v5/moon-phase/now-utc — the above for the current moment at Greenwich
  • /api/v5/moon-phase/context and /api/v5/moon-phase/now-utc/context — same data packaged as AI-optimised XML

Context endpoints — AI and LLM integration

Every major chart type has a /api/v5/context/ counterpart that returns a context key containing a structured XML string instead of an SVG. These are designed for passing directly to a language model. The provider also ships an llms-full.txt single-file documentation bundle and a skill package installable via npx skills add g-battaglia/Astrologer-API, compatible with Claude Code, Cursor, Windsurf, Copilot, and several other agents. This level of LLM-tooling integration is unusual for an astrology API and signals that AI-native astrology features are an explicit design goal.

Pricing

Plan Price Requests/month Overage
BASIC $0 75 —
PRO $9 5,000 —
ULTRA $18 50,000 —
MEGA $40 1,000,000 $0.0003 each

The free BASIC tier gives you 75 requests per month. That is enough to explore all the endpoint families and verify the SVG output quality, but it will not sustain even a small production feature — a user opening a birth chart plus a compatibility score is already two requests. Most hobby or small-scale personal projects will need PRO at $9/month. Teams shipping to real users with moderate traffic will likely land on ULTRA at $18/month for 50,000 requests. The MEGA plan's per-request overage of $0.0003 makes cost predictable at high volume: one million overages beyond the included quota would add $300, which is unlikely to sneak up on you if you are monitoring usage.

Practical use cases

Dating and compatibility apps are the clearest fit. A single API call to /api/v5/chart/synastry gives you both a visual chart to display and the data to drive a compatibility score UI. The Ciro Discepolo endpoint offers an out-of-the-box scoring system if you do not want to implement your own.

Horoscope and personal astrology tools can use the birth chart and lunar return endpoints to give users monthly personal forecasts, with SVGs ready for display without any server-side rendering pipeline.

AI astrology chatbots can use the context endpoints to inject structured chart data into a prompt before asking an LLM to interpret it, sidestepping the token overhead of passing raw JSON and letting the XML structure guide the model.

Dashboards and SaaS tools that want a "what's happening in the sky right now" widget can poll /api/v5/now/chart or /api/v5/moon-phase/now-utc on a schedule.

Limitations and things to check before integrating

Latency. The 447 ms average latency is worth considering for synchronous user-facing flows. Chart rendering endpoints likely run slower than data-only endpoints. If you are building a high-interactivity UI, consider calling data endpoints first and lazy-loading SVGs, or caching results for common birth date inputs.

Success rate. A 97% average success rate is solid but not perfect. Budget for retry logic and graceful error states in your client code, especially if the API is on a critical user path.

Free tier constraints. 75 requests/month on BASIC amounts to roughly 2–3 requests per day. Do not build a multi-endpoint flow that you plan to test extensively on the free tier; you will exhaust the quota quickly. Upgrade to PRO for development work.

Older API versions. The endpoint list shows legacy v2, v3, and v4 routes still exposed. New integrations should target v5 exclusively. The older routes appear to offer a subset of functionality and have simpler response shapes.

Zodiac system. The zodiac_type parameter accepts "Tropical" or "Sidereal", which matters if your users have a preference. Confirm defaults match your audience's expectations before launching.

Getting started

  1. Subscribe on RapidAPI (the BASIC plan requires no payment details for 75 monthly requests).
  2. Grab your X-RapidAPI-Key from the RapidAPI dashboard.
  3. Send a POST to https://astrologer.p.rapidapi.com/api/v5/chart/birth-chart with a subject object containing the person's birth coordinates and timezone.
  4. The response JSON contains chart (SVG string) and chart_data (full astrological breakdown). Drop the SVG inline or into an <img src="data:image/svg+xml,..."> tag.
  5. For data-only workflows, swap the path to /api/v5/chart-data/birth-chart to skip SVG rendering.

Interactive Swagger documentation is available at kerykeion.net/astrologer-api-swagger/, and the full single-file docs at kerykeion.net/astrologer-api/llms-full.txt are worth fetching if you are using an AI coding agent to scaffold the integration.