Astral Astrology API

What this API is

The Astral Astrology API computes Western astrology as pure functions over a birth moment. Send a subject — an ISO 8601 datetime with offset, or a local time plus IANA timezone, with coordinates when houses are involved — and optional settings; get back structured data computed against the Swiss Ephemeris, from raw planetary positions to composed natal, synastry, composite, transit, progression, and return charts, plus Moon phase and void-of-course. The same input under the same calc_version returns the same digits, on every run and every machine — determinism the API versions, tests in CI, and echoes back in every response.

Provenance on every response

Every response echoes 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, subject.location.required — plus a request_id for support. Domain edge cases are documented codes, not a 400 with a string.

One schema everywhere

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

Both units, always

Every longitude ships as 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. Every endpoint below is callable right now:

Endpoint	Returns	Credits
POST /v1/western/positions	Planetary positions for the subject moment	1
POST /v1/western/houses	House cusps and angles (location required)	1
POST /v1/western/aspects	Pairwise aspects between the subject’s bodies	1
POST /v1/western/natal	Composed birth chart — positions, houses, aspects, distributions	2
POST /v1/western/synastry	Cross-chart aspects and house overlays for two charts	2
POST /v1/western/composite	Midpoint composite chart of two subjects	2
POST /v1/western/transits	Transiting positions and transit-to-natal aspects at a moment	2
POST /v1/western/transits/events	Exact transit-to-natal hits across a window, retrograde passes included	3
POST /v1/western/moon	Moon phase, void-of-course, sign, and next ingress	1 (2 with a window)
POST /v1/western/progressions	Secondary progressions of a natal chart to a target date	2
POST /v1/western/returns	Solar or lunar return chart	2
GET /v1/usage	The calling key’s own credit and request totals	0
GET /health	Process liveness with engine and calc_version	0
GET /ready	Engine readiness probe	0

/health and /ready need no API key; everything else takes a bearer key, and /v1/usage never charges credits. Every call’s cost is echoed in meta.credits_charged — see credits and metering for the full model.

Base URL: https://astral-external-api-iksoi6t3nq-ue.a.run.app. CI executes every example on this site against it on each build — if an example is here, it ran and passed.

Not live yet

Persisted chart resources with stable URLs and SVG wheel rendering, batch requests, and geocoding utilities are still to come. They will not appear in runnable examples until they ship. The changelog tracks 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/natal \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": {"datetime": "1990-05-15T14:30:00-04:00", "location": {"latitude": 40.7128, "longitude": -74.0060}}}'

That single request returns the whole chart — positions with house placements, cusps and angles, the aspect list with a summary, and element/modality/polarity/hemisphere distributions — wrapped in the provenance envelope (meta.calc_version, meta.settings_resolved, meta.subject_resolved, meta.credits_charged).

Start here

Your first birth chart in 10 minutesKey, one natal call, a full response walkthrough, local-time input, settings, and error handling — the whole loop.

Subjects and settingsThe one subject and settings schema every endpoint shares — datetime forms, bodies, house systems, and aspect orbs.

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.