Astrology API Documentation

R231 is live: 77 standard calculations plus the Pro Nakshatra Timeline are available, with the 500-request Free allowance and globally serial durable jobs.

Build Western, sidereal, and Vedic-oriented astrology applications with documented JPL DE421 calculation endpoints and structured JSON responses. Routes with a zodiac option default to tropical; request sidereal mode with Lahiri, Raman, Krishnamurti, Fagan–Bradley, Yukteshwar, Sassanian, True Chitra, True Revati, True Pushya, Galactic Center at 0 Sagittarius, or Galactic Alignment/Mardyks ayanamsa.

Planetary positions are calculated using bundled NASA JPL DE421 ephemeris data through Skyfield. Our calculation methodology explains the methods for houses, aspects, sidereal conversion, and other calculations, including their known limits. The Vedic beta routes and nakshatra timeline always use sidereal coordinates; each endpoint documents its exact scope.

Cosmic Ephemeris is a developer-first, server-to-server JSON API. It returns documented calculation data so your application can control interpretation and presentation.

Make your first request

1. Create a free account and generate a key on the API Keys page.
2. Store the key in your server environment as COSMICEPHEMERIS_KEY. The key is shown only once.
3. Send a JSON POST request to https://api.cosmicephemeris.com/api/astro/birth-chart with Authorization: Bearer authentication.
4. Read the returned chart object. Set zodiac: "sidereal" and ayanamsa: "lahiri" to request a sidereal chart.

Use the code example alongside this guide on your server. Never put the key in browser JavaScript or a mobile application bundle.

Documentation

• 🌍 Astrology Systems

  Tropical defaults, sidereal opt-in behavior, and calculation boundaries.

• 🔐 Authentication

  API-key authentication for programmatic access.

• 🧰 Developer Platform

  Projects, environment budgets, saved charts, teams, jobs, signed webhooks, exports, and MCP.

• 📍 Place, Timezone & Context

  Search versioned places, resolve historical civil time, and build deterministic model-ready fact bundles.

• 🌙 Birth Chart API

  Generate natal charts with planets, supported houses, and angles.

• 🪐 Transits API

  Compare a natal chart with a requested transit instant.

• ✨ Aspects API

  Calculate documented angular relationships.

• 🗓️ Planetary Events API

  Search bounded intervals for ingresses, stations, and exact major aspects.

• 🏠 House Ingress API

  Search transit crossings of fixed Equal or Whole Sign reference-chart cusps.

• 🔌 MCP Server

  Connect trusted agent hosts to all 78 live calculations with scoped server-side API keys.

• 🧪 Electional Reliability Research

  Explore the source-complete, not-yet-deployed hardening and minimax-regret audit.

• 🏠 Houses API

  Equal and whole-sign house calculations.

• 💞 Synastry API

  Compare two charts without compatibility scoring.

• 🌌 Sidereal Astrology

  Explicit sidereal coordinates and supported ayanamsas.

• 🕰️ Nakshatra Timeline

  Pro timeline calculations for supported sidereal bodies.

• Structured Horoscope (Beta)

  Deterministic transit signals and summary fields, with a separately labeled beta contract.

• Aspect Windows API

  Calculate exact-hit-anchored orb windows, repeats, and optional iCalendar text.

Developer downloads

Two optional tools to help you integrate Cosmic Ephemeris. Both cover the seventy-eight live endpoints below, including seventy-one beta additions. They describe how to call the API; they do not contain the calculation engine or introduce a new API version.

OpenAPI JSON — the API reference for your tools

A machine-readable description of the endpoints, authentication, accepted inputs, and response formats. Import it into compatible API tools to explore the contract and help build your integration. Download the OpenAPI JSON document.

Postman collection — ready-to-send example requests

Import the collection into Postman, set COSMICEPHEMERIS_KEY in a private, unsynced environment or supported secret store, and send example requests without first writing application code. Download the Postman collection.

Downloading or importing these files does not use your quota. Sending calculation requests does: attempts admitted for processing consume quota even if validation or calculation later fails. Never save your real API key in a shared collection or exported file, and do not configure automatic retries.

Endpoint and response reference

All endpoints below use POST and the same server API key. Their JSON response wrappers differ; use the documented field for each endpoint.

Choose your calculation settings

Western astrology uses the tropical default. Vedic-oriented applications can use sidereal charts and Moon nakshatra/pada data, plus beta D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150, Vimshottari through optional depth 4, Indian chart SVG and instant Panchang APIs. Regional calendars, festivals and complete Jyotish analysis are not implemented. Equal and whole-sign houses, plus opt-in beta Placidus, support both zodiacs.

• Supply an IANA timezone, such as Asia/Kolkata or America/New_York, when the date and time are local. Omission means UTC. Ambiguous or nonexistent local clock-change times return HTTP 400; send the known UTC instant instead.
• Public dates must fall between 1900-01-01 and 2050-12-31, inclusive.
• Chart latitude must be strictly between −90 and 90; longitude ranges from −180 to 180, inclusive. Exact poles and undefined Ascendant geometry return HTTP 400. The Panchang beta has the narrower latitude limit [-88,88]. Supply coordinates directly or use the separate place-search and historical-timezone onboarding workflow; calculation routes never overwrite explicit inputs.
• Legacy chart routes, natal SVG, composite, secondary-progressed planets, solar arcs, lunar nodes, returns and planetary events default to tropical; sidereal mode defaults to Lahiri when ayanamsa is omitted. Planetary-event stations retain tropical motion timing even when reported longitudes are sidereal. Vargas, Vimshottari, Panchang and Indian varga SVG are always sidereal with Lahiri default. The timeline is always sidereal and requires an explicit ayanamsa.

Review the calculation methodology for house models, mean lunar nodes, aspect orbs, and the ephemeris.

Quotas, errors, and retries

Free includes 500 standard requests per UTC calendar month; Developer (the API's basic plan) includes 10,000; Pro includes 100,000 plus 1,000 separate timeline units. Quotas reset at the UTC month boundary, independently of the subscription renewal date. See plans and pricing.

A request consumes a unit once it passes authentication, admission, and plan/quota checks and reserves usage. Later validation failures, engine errors, or timeouts still consume that unit. Limit your account to two simultaneous calculation requests and validate inputs before sending them.

• 400: correct the input; 401: check the key; 402: the timeline requires Pro.
• 429: quota, concurrency, or edge rate limit. Respect Retry-After when present; a monthly quota limit requires the next reset or a plan change.
• 502, 503, or 504: dependency failure, temporary busy/maintenance state, or timeout. Use bounded retries with backoff, respecting Retry-After; each retry can consume another unit.
• Check the HTTP status before parsing a successful response. Proxy errors are not guaranteed to be JSON.

Integration guides

• How to build an astrology app
• Astrology API versus an ephemeris library
• Understand API pricing and usage models
• Choose an endpoint for your application

// Node.js 22+ — server-side only
const response = await fetch("https://api.cosmicephemeris.com/api/astro/birth-chart", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.COSMICEPHEMERIS_KEY}`
  },
  signal: AbortSignal.timeout(20000),
  body: JSON.stringify({
    date: "2000-01-01",
    time: "12:00",
    timezone: "UTC",
    lat: 0.0,
    lon: 0.0
  })
});
if (!response.ok) throw new Error(`Cosmic Ephemeris HTTP ${response.status}`);
const data = await response.json();
console.log(data.chart);

# Python — server-side only
import os
import requests

url = "https://api.cosmicephemeris.com/api/astro/birth-chart"
payload = {
    "date": "2000-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 0.0,
    "lon": 0.0
}
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['COSMICEPHEMERIS_KEY']}"
}

response = requests.post(url, json=payload, headers=headers, timeout=20)
response.raise_for_status()
print(response.json()["chart"])