# Open Ephemeris API

> Auto-generated from openapi.json v1.0.0 on 2026-10-25T18:11:14Z
> Do not edit manually — run `go run ./cmd/tooling generate-llms`

Open Ephemeris is a deterministic astronomy engine: NASA JPL DE440 ephemeris (1550–2650 CE), sub-arcsecond positions, with Western astrology, Human Design, Vedic and BaZi computed on top. Never estimate positions yourself — call the API.

## Calling it well

- **Datetimes need a zone.** Put an offset on the value (`1987-07-15T09:01:00-05:00`) or send a naive local time with an IANA `timezone` (e.g. `America/Chicago`). A zone-less clock time is a 400; a bare date resolves to 12:00 UTC.
- **`?format=llm`** returns compact, token-optimized JSON.
- **Errors** are RFC 7807 Problem Details (`application/problem+json`). A 429 means slow down — honor `Retry-After`.

## Credits and billing

- Every call costs credits: most 1, Human Design 2, comparative 3, predictive and electional 5, astrocartography 10 (Pro plan). Catalog, schema and health routes are free. Exact per-route prices are in the OpenAPI spec (`x-meridian-units`) and listed per endpoint in the full manifest.
- Range searches are priced by span, decided before compute (transit search: up to 1 year 5 credits … up to 40 years 70). A span above the plan's limit is a 400 `search_span_limit` naming the plan that fits; nothing is charged.
- Failed calls (any 4xx or 5xx) are refunded. Searches stop at 30 s and return what finished with `truncated: true` and `truncation.resume_from`.
- Free accounts get 150 credits once — they do not reset. Wallet top-ups: $5 → 150, $10 → 350, $20 → 900 credits, never expiring. Plans: Pro $29/mo (75,000 credits), Startup $79/mo (500,000), Scale $199/mo (2,000,000).
- Subscribers (Pro, Startup, Scale) buy the same packs at half price on https://openephemeris.com/wallet, where they can also opt in to auto top-up (buys a chosen pack when the balance drops below a set mark, up to a monthly limit).
- **402 = out of credits.** Do not substitute your own data. Show the user the one-tap link in the response's `upgrade.topup_url` (it opens checkout directly, no sign-in; for subscribers it opens the half-price wallet page); otherwise https://openephemeris.com/pricing.

**Open Ephemeris Engine** - Professional Astrological Calculations

## Quick Facts

- **Base URL**: `https://api.openephemeris.com`
- **Auth**: `Authorization: Bearer <token>`, or an API key in `X-API-Key` (alias `X-OpenEphemeris-API-Key`)
- **Public Endpoints**: 136 (counted by path; the groups below also list health and metadata routes)
- **Agent Output Mode**: `?format=llm`
- **OpenAPI Spec**: https://api.openephemeris.com/openapi.json

## Endpoint Groups

- **ACG** (14 endpoints, GET, POST): Calculate Astrocartography Aspect Lines; Cyclocartography Time-Series (Go Engine); Transit Parans
- **Human Design** (11 endpoints, POST): Create Human Design Chart; Human Design Composite; Human Design Connection Matrix
- **Time Conversion** (6 endpoints, GET, POST): Delta T (TT-UT1) calculation; Equation of Time; Calendar conversion to Julian Day Number
- **agricultural** (3 endpoints, GET): Biodynamic monthly calendar; Biodynamic daily profile; Void of Course Moon
- **api-metadata** (8 endpoints, GET): API Root; Get Supported House Systems; Get Natal Chart Request Schema
- **calendar** (3 endpoints, GET): Wheel of the Year — True Astronomical Dates; Lunar Standstill — 18.6-Year Nodal Cycle Status; 8-Phase Lunar Classification + Next Principal Phases
- **catalogs** (3 endpoints, GET): Catalog of supported natal bodies; Catalog of fixed stars (paginated); Catalog of fixed star group identifiers
- **chinese** (12 endpoints, GET, POST): Calculate Four Pillars of Destiny (BaZi); BaZi Annual Pillar (Liu Nian); Render BaZi Chart (SVG/PNG)
- **comparative** (5 endpoints, POST): Calculate Composite; Calculate Composite Midpoint; Calculate Natal Transits
- **eclipse** (6 endpoints, GET): Raw Besselian Elements; Lunar Eclipse Global Circumstances; Next Eclipse
- **electional** (6 endpoints, GET, POST): Angle Crossing Search; Active Aspect Search; Find Electional Window
- **ephemeris** (23 endpoints, GET, POST): Calculate angles + points (granular); Calculate antiscia and contra-antiscia; Check aspects between two longitudes
- **health** (2 endpoints, GET): Global Health Check; Detailed Health Check
- **location-timezone** (5 endpoints, GET, POST): Search for locations by name; Reverse geocode coordinates to location name; Historical timezone overlay coverage report
- **lunar** (4 endpoints, GET): Get current Moon aspects; Get Moon sign ingresses for date range; Get lunar phase
- **predictive** (15 endpoints, POST): Calculate progressed chart (Secondary, Tertiary, Solar Arc); Mundane Chart; Eclipses That Hit a Natal Chart
- **tidal** (1 endpoints, GET): Astronomical Tidal Forcing
- **vedic** (5 endpoints, POST): Generate a Vedic (sidereal) natal chart; Vedic KP Chart; Vedic Ashtakoota Matching
- **venus-cycles** (6 endpoints, POST): Compute Venus Star Points; Range-based Venus conjunctions; Venus 8-year star pattern
- **visualization** (3 endpoints, POST): Generate Bi Wheel; Human Design Bodygraph; Generate Chart Wheel

## Documentation

- **Interactive API Reference**: https://openephemeris.com/docs
- **OpenAPI Spec (JSON)**: https://api.openephemeris.com/openapi.json
- **Full Agent Manifest**: https://openephemeris.com/llms-full.txt
- **ChatGPT app**: https://chatgpt.com/plugins/plugin_asdk_app_6a9c2787bc48819197698e71b29ef7c2 (one-click install from the ChatGPT app directory)
- **Remote MCP server**: `https://mcp.openephemeris.com/mcp` (Streamable HTTP, OAuth) for Claude and any hosted MCP client
- **MCP Tooling**: `npx -y @openephemeris/mcp-server` for local stdio integration