Astral Astrology API

What this API is

The Astral Astrology API computes Western astrology data as pure functions over a birth moment. Send a subject (an ISO 8601 datetime with an explicit UTC offset, plus optional coordinates) and optional settings; get back structured positions computed against the Swiss Ephemeris (currently 2.10.03). The same input against the same calc_version returns the same digits, on every run, on every machine. That determinism is a contract, not an aspiration — it is versioned, tested in CI, and echoed in every response.

Provenance on every response

Every response carries meta.calc_version, meta.settings_resolved (the full settings actually used, defaults included), meta.subject_resolved (the exact UTC moment and coordinates computed), and meta.credits_charged. Nothing is resolved silently.

Errors you can program against

Every error is an RFC 9457 problem document with a stable, namespaced code — auth.missing, settings.ayanamsa.not_applicable — plus a request_id for support. Domain edge cases are documented codes, not a 400 with a string.

One schema everywhere

One subject schema, one settings schema, one data/meta envelope. Integrate one endpoint and you have integrated them all — no per-endpoint parameter drift.

Both units, always

Every position ships decimal degrees and structured degrees/minutes/seconds side by side, so you never write the conversion — and never inherit its rounding bugs.

What’s live today

The API is in early access (Phase 0). The live surface is deliberately small:

Endpoint	Purpose
POST /v1/western/positions	Planetary positions for a subject moment (1 credit)
GET /health	Process liveness, engine and calc_version info (unauthenticated)
GET /ready	Engine readiness probe (unauthenticated)

Base URL: https://astral-external-api-iksoi6t3nq-ue.a.run.app. All examples in these docs use it, and CI executes them against it on every build — if an example is on this site, it ran and passed.

Upcoming — not live yet

Houses and angles are next, followed by the composed natal endpoint, deterministic chart URLs with SVG wheels, synastry, and transits. None of these are callable today, and they will not appear in runnable examples until they are. See the changelog for what has actually shipped.

One call

During early access, API keys are provisioned manually — there is no self-serve signup yet. Once you have a test key, export it and you are one request away from data:

export API_KEY=ak_test_your_key_here

curl -s https://astral-external-api-iksoi6t3nq-ue.a.run.app/v1/western/positions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"datetime": "1992-11-22T08:45:00+05:30", "location": {"latitude": 28.6139, "longitude": 77.209}}}'

Start here

Your first chart data in 10 minutesKey, request, response walkthrough, settings, and error handling — the whole loop.

AuthenticationBearer keys, test vs live prefixes, and rotation.

ErrorsThe RFC 9457 problem shape and the stable code catalog.

Determinism and calc_versionWhy identical inputs return identical digits, and what a calc_version bump means.

API referenceInteractive reference rendered from the live OpenAPI spec — never a stale copy.

ChangelogContract-level changes: endpoints, schemas, and calc_version history.