Calculate · Integrate · Explore

Astrology API Documentation

Integrate the astrology API with documented endpoints, authentication guides and Node.js, TypeScript or Python SDKs. Explore birth charts, synastry, transits, Vedic calculations and separate readings APIs.

  • 78 calculation APIs
  • 1000 BCE–2500 CE historical inputs
  • Western and Vedic-oriented tools

All 78 documented calculations are live: 77 standard calculations are available on every plan, and Pro adds Nakshatra Timeline. Free includes 500 standard requests per UTC calendar month. Durable jobs execute one at a time across the service.

Learn by building: astrology API tutorials and Node.js examples →

AI documentation (llms.txt) — a concise guide to the API, SDKs and MCP integration for coding assistants.

01 / Start here

Get your first integration working

Credentials, official clients and complete request examples.

02 / Foundations

Charts, inputs & relationships

Understand the input conventions, then choose the calculation you need.

03 / Timing

Transits, events & calendars

Search bounded intervals and work with documented timing limits.

04 / Sidereal

Sidereal & Vedic-oriented tools

Explicit conventions and route-specific capabilities—not a claim of complete traditional coverage.

05 / Product features

Readings, visuals & advanced tools

Choose structured text, chart graphics, reports or bounded research calculations.

06 / Production

Operate your integration

Team controls, async workflows, agent access and advanced reliability evidence.

Symbolic readings, Tarot and Vedic systems have a separate supplemental HTTP API and the cosmicephemeris_symbolic MCP tool. They complement, rather than change, the 78-operation catalog. Node/Python 0.5.0 supports all three supplemental methods. Reading prose and translations are AI-assisted symbolic reflections, not scientifically validated predictions or professional advice.

Integration reference First request, downloads, endpoint fields, historical dates and limits

Calculation foundations

Build Western, sidereal, and Vedic-oriented astrology applications with documented 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 DE440 and historical DE441 ephemeris data through Skyfield. Our calculation methodology explains the methods for houses, aspects, sidereal conversion, and other calculations, including their known limits. The Vedic-oriented 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 least-privilege key from the API Keys area of your dashboard.
  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 HTTP examples below on your server, or start with the official SDKs. Never put the key in browser JavaScript or a mobile application bundle.

// 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"])

Developer downloads

Four integration resources cover all seventy-eight live endpoints with contract status and method limits documented per operation. They describe how to call the API; they do not contain the calculation engine or introduce a new API version.

Complete request and response catalog

The complete API examples catalog provides generated cURL, Node.js SDK, and Python SDK requests plus one schema-validated successful response for each of the 78 live calculations.

Import-ready OpenAPI and Postman files

Import the OpenAPI 3.1 document into a compatible API tool, or import the Postman collection, set COSMICEPHEMERIS_KEY in a private, unsynced environment or supported secret store, and send the included synthetic requests. Never save a real key in a shared collection or export.

Jupyter quickstart and CSV workflow

The downloadable Python notebook installs the pinned public client, reads the API key only from COSMICEPHEMERIS_KEY, runs synthetic birth-chart and event-calendar examples, and writes JSON and CSV files without placing a credential in the notebook.

  1. Set COSMICEPHEMERIS_KEY in the notebook server's private environment, then open the downloaded notebook.
  2. Run the installation and setup cells without pasting the key into a cell, output, filename, or shared notebook.
  3. Run the event-calendar cell with include_csv: true; it writes cosmic-ephemeris-events.csv.
  4. Open that UTF-8 CSV in a spreadsheet. One row represents one ordered event from the bounded request.

CSV is an opt-in output only on documented export-capable operations, including event calendar and selected report or astrocartography formats. It is not a generic request format: normal calculations accept JSON, while bounded batch import accepts NDJSON—not CSV.

Downloading or importing these resources does not use quota. Sending calculation requests does: attempts admitted for processing consume quota even if validation or calculation later fails. Do not configure automatic retries.

Each account can run up to 2 calculations concurrently, maintain 5 active API keys and 50 saved chart profiles, and queue up to 10 active batch jobs containing 10 items each. Monthly plan quotas still apply.

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.

PathWhere to read the result
/api/astro/birth-chartchart
/api/astro/aspectsThe aspect array is aspects.aspects; its parent contains the full chart.
/api/astro/houseshouses.systems, with normalized house_system at the top level.
/api/astro/transitstransits.natal_chart, transits.transit_chart, and transits.aspects
/api/astro/synastrycharts.personA, charts.personB, and aspects
/api/astro/nakshatra-timelineTop-level segments and timeline metadata; Pro required.
/api/astro/horoscopeinterpretation; current.
/api/astro/natal-svgsvg as a string inside JSON; current.
/api/astro/vargasascendant and bodies; twenty-four supported divisions from D1 through D150, with named conventions and D150 method selection; current.
/api/astro/vimshottaribirth_balance, cycle, and periods; optional third/fourth levels with depth: 3/4; current.
/api/astro/davisonmidpoint, physical planets, angles, houses and aspects; current uncorrected TT/arithmetic method.
/api/astro/compositeplanets, angles, synthetic houses and aspects; current.
/api/astro/panchangtithi, nakshatra, yoga, karana, vara and solar_events; current, latitude [-88,88].
/api/astro/ashtakootaEight directional koota component scores and total out of 36 without a threshold verdict or interpretation; current.
/api/astro/ashtakavargaSeven-planet Bhinnashtakavarga, contributor Prastara, 337-point Sarvashtakavarga, and explicit opt-in reductions/pindas without interpretation; current.
/api/astro/numerologyDeclared Pythagorean date/name arithmetic with reduction traces and explicit calendar-year cycles; symbolic supported, no interpretations or predictions.
/api/astro/secondary-progressionsprogressed_planets, timing and separate natal_context; current, no progressed angles/houses.
/api/astro/varga-svgsvg and chart (Vargas result), with optional deterministic PNG; North/South Indian layouts for all twenty-four supported divisions; current.
/api/astro/lunar-nodesSeparate mean and geometric osculating true north/south node pairs with explicit frames; current.
/api/astro/solar-arcsDefault true-Sun or explicit mean-Naibod solar-arc directed planets and angles, synthetic Equal/Whole Sign houses and explicit timing; current.
/api/astro/returnsNext Sun/Moon longitude return, return_utc, chart and bounded search metadata; current.
/api/astro/moon-phasesInstant phase geometry or a bounded primary-phase calendar in result, with explicit model metadata; current.
/api/astro/planetary-eventsBounded sign ingresses, tropical stations, and exact major-aspect crossings in result.events; current.
/api/astro/house-ingressesDirect/retrograde transit crossings of fixed Equal or Whole Sign reference-chart cusps; current.
/api/astro/aspect-windowsExact-hit-anchored orb intervals, applying/separating labels, repeats and optional iCalendar text in result; current.
/api/astro/event-calendarUnified Moon, ingress, station, exact-aspect and aspect-window events, plus optional grouped aspect passes and iCalendar; current.
/api/astro/event-rule-searchBounded customer-defined AND/OR fact rules with validation, cost estimates, matching intervals, saved versions, schedules, and calendar output; current.
/api/astro/convention-compareField-level comparison of two explicit zodiac, ayanamsa, and house-system profiles for the same birth input; current.
/api/astro/chart-robustnessSampled stability classifications across unknown or approximate birth time and two or three explicit convention profiles; current, non-exhaustive, never rectification or convention ranking.
/api/astro/civil-time-auditNever-guess local-time resolution: both repeated-time chart candidates with exact 22-fact differences, or no chart for a nonexistent time; current.
/api/astro/chart-input-readinessMachine-readable exact-route readiness and resolved, candidate, or sampled evidence for exact, ambiguous, nonexistent, approximate, or unknown birth time; current, never rectification.
/api/astro/house-system-readinessFixed 25-system geometry readiness, cusp fingerprints, downstream route readiness, and explicit no-fallback evidence; current.
/api/astro/house-placement-stabilityUnweighted planet-house agreement across comparable systems, deterministic placement groups, and explicit no-fallback evidence; current.
/api/astro/aspect-policy-stabilityCompare 2–4 explicit aspect-orb policies on one chart with reason states, signed margins, set fingerprints, and deterministic equivalence groups; current.
/api/astro/house-boundary-proximityExact two-sided cusp clearance and normalized position for selected planets across every available 12-house system, with explicit failures and no fallback; current.
/api/astro/location-precision-auditNine-point coordinate-radius audit for one explicit 12-house system, with house stability, angle/cusp displacement, explicit failures, and no fallback; current.
/api/astro/location-transition-scanCenter plus 64 fixed radial checkpoints for observed angle-sign, cusp-sign, and selected planet-house transition brackets, with explicit geometry failures and no full-disk guarantee; current.
/api/astro/chart-uncertainty-envelopeFull-factorial seven-time by nine-location sampled evidence separating time-axis, location-axis, combined, and interaction-only observed variation; current.
/api/astro/synastry-svgOriginal deterministic double-wheel SVG in JSON, with optional deterministic PNG; current.
/api/astro/transit-svgOriginal deterministic natal/transit double-wheel SVG in JSON, with optional deterministic PNG; current.
/api/astro/natal-reportStandalone calculation-fact HTML, source-linked facts, and optional integrity-checked download bytes; no interpretation; current.
/api/astro/birth-time-sensitivityObserved sensitivity for exact intervals or explicit unknown/approximate birth time; current, non-exhaustive, never rectification.
/api/astro/fixed-starsSix independently validated fixed stars only; no minor bodies; current.
/api/astro/relocation-chartSame birth instant and geocentric positions with destination angles and selected houses; current.
/api/astro/astrocartographyBounded MC/IC and sampled rising/setting geometry; no maps, rankings, or interpretations; current.
/api/astro/eclipse-geometryBounded global solar/lunar eclipse geometry with optional observer snapshot at global maximum; no local contacts or paths; current.
/api/astro/electional-searchAND-only electional filters on a fixed hourly grid; no ranking, continuous guarantee, or advice; current.
/api/astro/electional-robustness-auditStress-test electional criteria across start-time and venue uncertainty; current, with bounded sampled evidence.
/api/astro/electional-tolerance-frontierMeasure observed electional rule tolerance in time and venue directions; current, with bounded sampled evidence.
/api/astro/electional-feasibility-auditExplain sampled electional feasibility and minimal observed rule relaxations; current, with bounded sampled evidence.
/api/astro/electional-resolution-auditShow which observed electional match runs coarser sampling misses; current, with bounded sampled evidence.
/api/astro/electional-sampling-phase-auditShow whether electional results change with the sampling anchor; current, with bounded sampled evidence.
/api/astro/electional-criterion-omission-auditMeasure which selected electional criteria uniquely exclude observed samples; current, with bounded sampled evidence.
/api/astro/electional-criterion-pair-auditExpose observed two-criterion electional exclusion interactions; current, with bounded sampled evidence.
/api/astro/electional-criterion-relation-auditExpose observed compatibility and redundancy among electional criteria; current, with bounded sampled evidence.
/api/astro/electional-criterion-budget-auditFind every optimal electional rule-relaxation combination by exact omission budget; current, with bounded sampled evidence.
/api/astro/electional-criterion-budget-stability-auditAudit whether optimal electional rule relaxations survive sampling-grid changes; current, with bounded sampled evidence.
/api/astro/electional-criterion-budget-regret-auditFind least sampling-sensitive electional rule relaxations by exact minimax regret; current, with bounded sampled evidence.
/api/astro/electional-criterion-budget-pareto-auditEnumerate weight-free Pareto-efficient electional rule relaxations; current, with bounded sampled evidence.
/api/astro/electional-criterion-shapley-auditAttribute excluded electional samples fairly across interacting criteria; current, with bounded sampled evidence.
/api/astro/electional-criterion-conflict-core-auditFind the smallest electional rule combinations that make a window infeasible; current, with bounded sampled evidence.
/api/astro/electional-criterion-robust-repair-auditFind the smallest criterion relaxations that work across every sampling grid; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-impact-auditAudit what every minimal cross-grid criterion repair actually admits; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-distinction-auditProve how every pair of minimal cross-grid criterion repairs differs; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-overlap-auditClassify exact overlap and containment for every minimal repair pair; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-hierarchy-auditBuild the exact containment hierarchy of minimal repair consequences; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-coverage-auditAudit exact observation support and single-repair coverage loss; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-resilience-auditAudit exact multi-repair failure tolerance; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-loss-frontier-auditAudit exact worst-case repair-loss damage; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-hardening-auditAudit exact single-repair hardening effects; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-hardening-pareto-auditCompare exact repair-hardening Pareto tradeoffs; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-hardening-pareto-hierarchy-auditMap the exact hierarchy of repair-hardening Pareto profiles; current, with bounded sampled evidence.
/api/astro/electional-criterion-repair-hardening-regret-auditFind every least-worst-regret repair-hardening profile; current, with bounded sampled evidence.
/api/astro/natal-analysisConfigured aspects, midpoint axes, geometric patterns, and strict opt-in sidereal Parashari graha drishti; no interpretation; current.
/api/astro/planetary-hoursTwenty-four unequal sunrise-based day/night temporal hours and Chaldean rulers; no advice; current.
/api/astro/place-searchDeterministic self-hosted GeoNames place candidates with versioned IDs and attribution; current.
/api/astro/timezone-resolvePinned historical IANA civil-time resolution with explicit unique, ambiguous, or nonexistent status; current.
/api/astro/natal-contextDeterministic fact IDs, source paths, fingerprints, and JSON/XML/Markdown artifacts without generated interpretation; current.

Choose your calculation settings

Western astrology uses the tropical default. Vedic-oriented applications can use sidereal charts and Moon nakshatra/pada data, plus supported 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. Supplemental Vedic systems add Yogini periods, regional calendar factors and North/South Hindu calendar presets with 18 named observances each. These are not complete regional calendars or complete Jyotish analysis. The Houses endpoint's 25-choice inventory supports both zodiacs; Natal SVG supports its 24 twelve-house systems, while Gauquelin remains Houses-only.

  • 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.
  • Standard civil date strings support 1800-01-01 through 2200-12-31, inclusive. All date-bearing operations also accept explicit historical inputs; see the historical boundary below.
  • 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 supported 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.

Historical dates: 1000 BCE (BC)–2500 CE (AD)

All 77 date-bearing operations accept explicit historical inputs from 1000 BCE (BC) through 2500 CE (AD). The 78th operation, place-search, is date-independent. This includes Western and Vedic calculations, electional audits, Moon phases, eclipses, fixed stars, maps and rendering. Existing search-window, polar-geometry and resource limits still apply; a historical date range is not a promise that every geographic configuration or export format is valid.

Numerology requires an explicit year_convention: displayed_year_digits (1000 BCE uses 1000) or astronomical_year_digits (1000 BCE uses the digits of −999; 1 BCE uses 0). The minus sign is not a digit. These are symbolic choices, not established ancient practices, and numerology has no astronomical time scale. Timezone and readiness tools require a caller-supplied UT1 convention; modern city data does not establish ancient legal time.

Use era: "BCE" or era: "CE", a positive year with no year zero, and an explicit proleptic_gregorian or proleptic_julian calendar. Historical input requires UT1 or an explicit fixed UT1 offset; UTC and IANA zones are not accepted in this mode. Never assume a modern timezone applied in antiquity.

See the historical input example and timekeeping caveats and each operation's OpenAPI schema. The same bodies work through MCP. DE441 supplies ancient positions and DE440 supplies the later range; ancient timekeeping and model uncertainty remain explicit. Houses may be undefined, searches remain bounded, and coverage is not full-range independent accuracy certification.

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

Explore all six developer projects with runnable code and sample results.