Ephemeris API for planetary positions and celestial events

01 / Method

A stable API starts with explicit contracts

Astronomical output depends on the instant, time model, coordinate options and reference data. The API therefore returns a structured result envelope with request identifiers, warnings, errors, calculation metadata and a result hash where supported.

Profiles make groups of calculation choices reusable and auditable. Clients can pin a profile instead of relying on changing implicit defaults.

• Typed JSON request and response schemas
• API-key authentication and quota responses
• Deterministic result envelopes
• Version and capability discovery endpoints

02 / API example

Call the v2 ephemeris endpoint

This request selects five bodies. Omitting the body list selects the supported default catalog; an explicitly empty list is rejected.

curl --request POST \
  --url https://api.chronos-ephemeris.com/v2/ephemeris \
  --header "Authorization: Bearer $CHRONOS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "datetime_utc": "2026-07-16T12:00:00Z",
    "bodies": ["sun", "moon", "mercury", "venus", "mars"],
    "profile": "chronos.standard@1"
  }'

Keep API keys in server-side secret storage. The example uses an environment variable and contains no production credential.

03 / Evidence

Operational and numerical evidence

The public capability registry reports supported bodies, house systems, ayanamshas, coordinate modes and event types. The Validation Center publishes error-budget descriptions, known limitations and downloadable release evidence.

Clients should handle validation errors, authentication failures, quota responses and engine failures as distinct states. Retrying an invalid calculation does not make it valid.

04 / Applications

One API, multiple product surfaces

ChronOS is designed for backend services, websites, mobile applications and agent tools that need celestial calculations without embedding a separate astronomical stack in every client.

• Mobile astrology and astronomy apps
• Calendar and notification services
• Chart rendering pipelines
• AI agents using structured function schemas

05 / FAQ

Frequently asked questions