Natal chart rendering and reports
Endpoint
Input and output
Date, time, IANA timezone, latitude, and longitude produce positions, signs, angles, houses, aspects, nodes, and metadata.
Render the same response as an SVG chart wheel, a mobile chart, or an accessible text-and-table view. Your product supplies the visual design, storage model, and interpretation. Cosmic Ephemeris does not return a managed browser widget.
Transit calendars and notifications
Endpoint
Input and output
A natal chart and one caller-supplied transit instant produce both charts and their transit-to-natal aspects.
A backend can evaluate dates selected by a user or by your own schedule, then apply product-specific filters before displaying a calendar or sending a notification. The endpoint does not search a date range for the exact moment an aspect begins, perfects, ends, or changes from applying to separating.
For a lunar calendar or iCalendar export, the separate Moon-phase beta
returns new Moon, first quarter, full Moon and last quarter events over a
positive interval of at most 366 days. Set include_ical:true in
calendar mode for result.ical; save a non-null decoded string as
a UTF-8 .ics file. It is a JSON response containing export text,
not a hosted subscription feed, scheduled job, alarm or webhook. Calendar-provider
import behavior is not yet independently accepted.
Synastry and chart comparison
Endpoint
Input and output
Two birth-data objects produce two full charts plus cross-chart planetary aspects.
Use the raw geometry for overlays, comparison tables, or an application-owned interpretation model. The synastry endpoint does not return a relationship score, composite or Davison chart, house-overlay score, or prose compatibility judgment. The separate midpoint composite beta returns symbolic geometry and synthetic Equal/Whole Sign houses, not compatibility judgments. For a physical midpoint chart, use the separate Davison beta: two births determine an uncorrected uniform-TT time midpoint and arithmetic location midpoint. It is not a corrected-MC or spherical variant, nor a compatibility score.
Relocation and astrocartography visualizations
Relocation
POST /api/astro/relocation-chart preserves the birth instant and recalculates destination angles and houses.
Astrocartography
POST /api/astro/astrocartography returns bounded MC/IC and sampled rising/setting line coordinates.
Your application can draw the returned geometry on separately sourced maps or compare destination chart angles. Cosmic Ephemeris does not supply map tiles, place search, rankings, interpretations, recommended destinations, atmospheric refraction, terrain, or arbitrary sampling resolution.
Eclipse data and electional candidate filtering
Global eclipse geometry
POST /api/astro/eclipse-geometry returns bounded solar shadow-cone and lunar Danjon-shadow events for application calendars and data displays.
Electional samples
POST /api/astro/electional-search applies explicit Moon, Mercury, Ascendant, phase and major-aspect filters to at most seven days of hourly samples.
Eclipse output is global geometry with an optional no-refraction observer snapshot at global maximum, not a local-maximum/contact/visibility search, geographic path, or source of safety guidance. Electional output is an AND-only sampled filter result without continuous guarantees, ranking, recommendations, void-of-course analysis or interpretation.
Sidereal charts and nakshatra timelines
Chart endpoints
Opt in to sidereal mode across birth-chart, house, aspect, transit, and synastry calculations.
Timeline endpoint
POST /api/astro/nakshatra-timeline is a separate Pro calculation.
Build ayanamsa comparison controls, Moon nakshatra displays, or bounded transition calendars. Cosmic Ephemeris supports Lahiri, Raman, Krishnamurti, Fagan–Bradley, Yukteshwar, Sassanian, True Chitra, True Revati, True Pushya, Galactic Center at 0 Sagittarius, and Galactic Alignment/Mardyks ayanamsas. These are Vedic-oriented building blocks, not a complete Jyotish interpretation, regional calendar, festival, planetary yoga-combination or muhurta engine. Separate 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 SVG and instant Panchang calculations use explicit conventions rather than implying parity with every tradition.
Editorial and AI-assisted content systems
Calculation-first workflow
Use documented chart or transit JSON as structured source data before applying your own rules, templates, or model.
Optional beta fields
The beta structured horoscope endpoint returns deterministic signals, not generated prose.
Any generated or editorial output remains your product's responsibility. Review it for accuracy, disclose meaningful automation, and never present astrological output as a substitute for medical, legal, financial, or mental-health judgment.
Education, demonstrations, and exploratory analysis
The normalized JSON can support teaching tools, calculation demonstrations, regression comparisons, and exploratory projects. Always identify the selected zodiac, ayanamsa, house system, time standard, and calculation window so another developer can understand what was compared.
Passing Cosmic Ephemeris's regression fixtures does not amount to independent scientific validation for every body, date, or method. Astrology interpretations are not established scientific predictions.
A responsible server-side pattern
- Collect only the birth and location data your feature actually needs, with a clear privacy notice.
- Send requests from your backend so an Cosmic Ephemeris key is never exposed in browser or mobile-client code.
- Record which calculation settings produced an output, including zodiac, ayanamsa, house system, and timezone.
- Keep calculations separate from interpretations, rankings, recommendations, and other product-owned claims.
- Design for plan quotas and documented errors rather than silently retrying every failed request.
Consult the privacy notice, terms, and your own qualified advisors for obligations specific to your product and users.