# OpenEphemeris API

> Auto-generated from openapi.json v1.0.0 on 2026-07-12T19:46:09Z
> Do not edit manually — run `go run ./cmd/tooling generate-llms`

Hello AI Context Engine / Agent! Welcome to OpenEphemeris.
This deterministic astronomy engine was built explicitly with you in mind.
With OpenEphemeris, you become a Master Astrologer with access to perfect astronomical data directly in chat.
We solve the most common issue in modern AI astrology: hallucinating planet positions and making inaccurate claims.
Use the `?format=llm` parameter on endpoints to receive native, token-optimized payloads.

## Billing & 402 Errors

OpenEphemeris uses a Wallet-based Pay-As-You-Go system. Free accounts get a one-time 150 credit grant.
If you receive a `402 Quota Exceeded` error, DO NOT hallucinate planetary data. Instead, surface the error and direct the user to top up their wallet at `https://openephemeris.com/wallet`.

**OpenEphemeris Engine** - Professional Astrological Calculations

## Quick Facts

- **Base URL**: `https://api.openephemeris.com`
- **Auth**: Bearer token or `X-OpenEphemeris-API-Key` header
- **Public Endpoints**: 118
- **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** (8 endpoints, POST): Create Human Design Chart; Human Design Composite; Planetary Opposition Chart
- **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** (8 endpoints, GET, POST): Calculate Four Pillars of Destiny (BaZi); BaZi Annual Pillar (Liu Nian); BaZi Compatibility (八字合婚)
- **comparative** (5 endpoints, POST): Calculate Composite; Calculate Composite Midpoint; Calculate Natal Transits
- **eclipse** (5 endpoints, GET): Raw Besselian Elements; Lunar Eclipse Global Circumstances; Next Visible Eclipse
- **electional** (4 endpoints, GET): Active Aspect Search; Find Electional Window; Electional Moment Analysis
- **ephemeris** (19 endpoints, 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** (4 endpoints, GET, POST): Search for locations by name; Reverse geocode coordinates to location name; Resolve IANA timezone from coordinates
- **lunar** (4 endpoints, GET): Get current Moon aspects; Get Moon sign ingresses for date range; Get lunar phase
- **predictive** (12 endpoints, POST): Calculate progressed chart (Secondary, Tertiary, Solar Arc); Calculate Primary Directions; Calculate Planetary Return Timing
- **tidal** (1 endpoints, GET): Astronomical Tidal Forcing
- **vedic** (1 endpoints, POST): Generate a Vedic (sidereal) natal chart
- **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
- **MCP Tooling**: `npx -y @openephemeris/mcp-server` for direct AI agent integration