Natal analysis, planetary hours, eclipse, electional, and expansion APIs

Thirteen bounded beta endpoints for application backends. Each admitted call uses one standard quota unit; failed or timed-out admitted attempts are not refunded. Keep API keys server-side and do not automatically retry.

Public calculation dates are bounded from 1900-01-01 through 2050-12-31. The public gateway is https://api.cosmicephemeris.com/api/astro/.

Symbolic numerology arithmetic

POST /api/astro/numerology uses the fixed beta convention pythagorean_component_sum_v1. Supply a valid Gregorian birth_date in YYYY-MM-DD form, from 1900 through 2050. Life path reduces the month, day and year separately, then reduces their sum; birthday_root reduces the day of month. Every number includes its original total and ordered reduction steps.

Optional name accepts 1–96 ASCII letters with internal spaces, apostrophes or hyphens. Supply your own explicit transliteration; the API does not infer spelling, pronunciation or ethnicity. The mapping repeats A=1 through I=9, ending Z=8. Expression uses all letters, soul urge uses AEIOU, and personality uses the remaining letters. Strict y_vowel:true assigns every Y to the vowel set; omission keeps Y consonantal. The option requires a name, even when false. Empty letter subsets return null, not a zero-valued number.

Strict master_numbers defaults to true and preserves 11, 22 and 33 at each component, name-total and final reduction; false reduces these to one digit. Optional integer year (1900–2050) adds a personal-year cycle by reducing raw birth month + raw birth day + requested calendar year to one digit regardless of the master-number option. It never defaults to the server clock and does not use a birthday-to-birthday boundary.

{"birth_date":"2000-01-01","name":"Ada Lovelace","year":2026,"master_numbers":true,"y_vowel":false}

This synthetic example produces life path 4, expression 9, soul urge 1, personality 8 and personal year 3. These are symbolic classifications, not scientifically validated personality assessments, compatibility verdicts, predictions or health/financial advice. Interpretations and practitioner approval are not included. Names and dates appear in the response; protect them as personal data. This synchronous-only calculation uses one standard unit on every plan, the astro:numerology or astro:* scope, and no new batch operation.

Unified event calendar

POST /api/astro/event-calendar composes Moon phases, sign ingresses, stations, exact major aspects, and exact-hit-anchored aspect windows. Supply a whole-second UTC interval longer than zero and no more than 31 days, plus one or more event_types. Non-lunar selections require explicit bodies; aspects require at least two. Optional display_timezone adds local timestamps, include_ical returns bounded RFC 5545 text inside JSON, and strict include_csv: true adds deterministic fixed-column UTF-8 RFC 4180 text in result.csv. The CSV uses CRLF records, a fixed 30-column header, and exactly one row per ordered event; omission or false preserves the predecessor response. Strict group_passes: true requires aspect or aspect_window and adds at most 225 request-window groups. Each group has a stable aspect-series identity, observed/clipped bounds, source event IDs, and deduplicated ordered exact contacts. The grouping does not join separate requests or imply one universal retrograde-cycle interpretation. Omission or false preserves the predecessor response. Cosmic Ephemeris does not host a subscription feed or create external-calendar events.

{"start_utc":"2026-09-01T00:00:00Z","end_utc":"2026-09-08T00:00:00Z","event_types":["moon_phase","aspect"],"bodies":["sun","moon"],"display_timezone":"America/New_York","include_ical":true,"include_csv":true,"group_passes":true}

Synastry and transit double-wheel SVG

POST /api/astro/synastry-svg accepts personA and personB. POST /api/astro/transit-svg accepts a birth plus a required transitDate. Both return an original deterministic 1200×1120 SVG string in JSON, support tropical or sidereal positions, Equal, Whole Sign, or beta Placidus inner houses, exact light/dark/monochrome themes, and optional major cross-chart aspect lines. Monochrome is a fixed grayscale palette, not an accessibility certification. Strict boolean include_png: true additionally returns a deterministic PNG, decoded byte count, dimensions, PNG SHA-256, and exact source-SVG SHA-256; omission or false preserves the SVG-only response. They accept no uploaded SVG, markup, image, font, or URL; SVG output is capped at 192 KiB and PNG bytes at 1 MiB.

Calculation-fact natal report

POST /api/astro/natal-report returns bounded standalone HTML plus a structured facts array. Every displayed fact has a stable ID and a source path back to the calculated chart field. An original natal SVG is included by default and can be disabled with include_svg: false. Exact light, dark, or monochrome themes are supported; omission retains dark.

Strict include_download: true adds download with a fixed safe filename, media type, strict base64 bytes, decoded byte count, and SHA-256. Omit download_format or use html for the exact standalone HTML; use exact pdf for an Cosmic Ephemeris-branded deterministic PDF; use exact docx for editable macro-free OOXML; use exact xlsx for a deterministic eight-member, formula-free and macro-free OOXML workbook; use exact ods for a deterministic five-member, formula-free and macro-free ODF 1.3 spreadsheet whose literal id, label, value, and source cells reproduce the response facts; use exact epub for a deterministic five-member offline, script-free EPUB 3 publication; use exact odt for editable macro-free ODF 1.3 text; use exact rtf for editable dependency-free Rich Text Format; use exact json for schema-bound calculation facts; use exact csv for fixed-column tabular facts; use exact xml for fixed-order schema-identified fact elements; use exact ndjson for canonical one-record-per-fact JSON Lines; use exact tsv for escaped fixed-column tab-separated facts; use exact markdown or text for deterministic UTF-8; use exact zip for the unchanged fixed bundle. A format is valid only with the explicit download opt-in.

{"birth":{"date":"2000-01-01","time":"12:00","timezone":"UTC","lat":0,"lon":0},"include_svg":true,"include_download":true,"download_format":"html","report_branding":{"display_name":"North Star Studio","accent":"blue"}}

Decode the base64, verify its length and digest, and save it using the returned fixed filename. HTML is capped at 512 KiB; every artifact is capped at 1 MiB. RTF is deterministic ASCII with fixed formatting controls and no objects, fields, images, hyperlinks, remote resources, or customer content. ODT retains only its five fixed package members. DOCX and ODT remain macro-free and externally isolated. The predecessor ZIP remains unchanged. Omission or false preserves the earlier response, the request still costs one standard unit synchronously or as a durable-job item, and Cosmic Ephemeris stores no report beyond the job surface's ordinary 24-hour encrypted result retention.

The HTML has a restrictive embedded Content Security Policy, no scripts, and no external resources. Optional report_branding provides escaped text-only HTML co-branding with a 1–64 character display name, exact amber/blue/green fixed accent, visible Cosmic Ephemeris attribution, and unchanged calculation facts. It accepts no logo, URL, markup, stylesheet, template, or remote resource and cannot be combined with non-HTML formats. This release does not provide email delivery, logo/full white-label branding, localization, generated or customer-supplied prose, user templates, tracked changes, or server-side editing. It is a calculation report—not generated interpretation, prediction, diagnosis, or advice.

Birth-time sensitivity

POST /api/astro/birth-time-sensitivity accepts either the existing positive civil-time interval of at most six hours or an explicit unknown/approximate birth-time workflow. Exact intervals and approximate times use fixed five-minute steps. Unknown time samples the complete local civil date every 30 absolute minutes; the required IANA timezone correctly reflects 23-, 24-, or 25-hour clock-change dates. Every mode includes both exact endpoints and returns at most 73 samples.

{"birth_time":{"status":"unknown","date":"2000-01-01","timezone":"America/New_York"},"lat":40.7128,"lon":-74.006}

{"birth_time":{"status":"approximate","date":"2000-01-01","time":"12:00","timezone":"America/New_York","uncertainty_minutes":30},"lat":40.7128,"lon":-74.006}

Workflow responses classify observed stable and variable sign/house points and explicitly report that no exact chart or representative time was selected and no rectification was performed. The result is not an exhaustive boundary solver, probability estimate, or birth-time rectification; unsampled changes are not excluded. Never relabel it as an exact natal chart.

Fixed-star positions

POST /api/astro/fixed-stars calculates explicitly selected Aldebaran, Antares, Fomalhaut, Regulus, Sirius, and Spica for a civil instant in tropical or supported sidereal longitude. The six-star catalog uses CC0 source rows and its implementation was independently compared with Astropy/ERFA at five epochs; maximum measured differences were 0.001008 arcsecond longitude and 0.003579 arcsecond latitude. This endpoint contains no asteroids or minor-body kernels. Minor-body calculations are not contracted or shipped; the never-live candidate routes were retired rather than depend on licensed source data.

{"at":{"date":"2026-09-23","time":"12:00","timezone":"UTC"},"stars":["aldebaran","regulus","sirius"],"zodiac":"tropical"}

Relocation chart

POST /api/astro/relocation-chart preserves the exact birth UTC instant and apparent geocentric planet and node positions, then recalculates the physical Ascendant, Midheaven, and Equal, Whole Sign, or beta Placidus houses at a supplied destination. A relocation does not change the birth time. Exact geographic poles are rejected because those angles and houses are undefined. The response contains calculation data only—no interpretation, score, or recommended location.

{"birth":{"date":"2000-01-01","time":"12:00","timezone":"UTC","lat":0,"lon":0},"location":{"lat":51.5074,"lon":-0.1278},"house_system":"placidus"}

Astrocartography geometry and downloadable maps

POST /api/astro/astrocartography returns MC and IC meridians plus sampled geometric rising and setting curves for 1–10 explicitly selected Sun-through-Pluto DE421 bodies. Longitudes use [-180,180); rising and setting curves use a fixed two-degree latitude grid from −88° through +88° and are split at the date line. Circumpolar points without a zero-altitude crossing are omitted. Set strict include_geojson: true for a deterministic RFC 7946 FeatureCollection with exactly four features per body in fixed MC, IC, ascendant, descendant order and longitude-latitude coordinates. Set independent include_geojson_seq: true for the same features as RFC 8142 RS-prefixed, LF-terminated records. Set include_ndjson: true for one compact GeoJSON Feature per LF-terminated line. Set include_topojson: true for deterministic unquantized TopoJSON with a named GeometryCollection and central arc inventory; it uses registered application/json. Set include_kml: true for deterministic OGC KML 2.2 and include_gpx: true for deterministic GPX 1.1. Set independent include_csv: true for deterministic RFC 4180 rows preserving body, angle, segment, point, longitude, and latitude order. Set independent include_wkt: true for one deterministic text GEOMETRYCOLLECTION, include_wkb: true for the same ordered geometry as OGC WKB 1.x little-endian binary, and include_gml: true for GML 3.2 using a CRS84 gml:MultiGeometry. All preserve date-line segments. Every artifact has a fixed filename/media type, base64 bytes, byte count, and SHA-256.

Set strict include_svg: true to receive Cosmic Ephemeris's deterministic 1200×800 coordinate-grid map. Add include_png: true for a metadata-free PNG with dimensions, decoded byte count, PNG SHA-256, and source-SVG SHA-256. Exact dark, light, and monochrome themes are available; the default export theme is dark. Omission or include_svg: false preserves the prior geometry-only response exactly. PNG and theme fields require explicit SVG opt-in.

GeoJSON plus decoded KML, GPX, CSV, WKT, WKB, and GML are each capped at 256 KiB and preserve the authoritative samples without interpolation. WKB is two-dimensional and contains no SRID, EWKB flags, Z/M coordinates, properties, or labels. GML contains no caller XML, schema location, external entity, or external resource. The returned lines remain numerically authoritative. SVG is capped at 192 KiB and PNG at 1 MiB. The same existing route, API-key scope, one-unit quota, and every-plan entitlement apply.

For real coastlines, set include_svg:true and basemap:"natural-earth-110m"; add include_png:true for its deterministic raster export. This bundles public-domain Natural Earth 1:110m coastline v4.1.0, with attribution and pinned provenance in metadata. There are no request-time map fetches. Omission or basemap:"coordinate-grid-only" preserves the original grid map. Both modes exclude political boundaries, place names, tiles, arbitrary resolution, refraction, topocentric parallax, terrain, interpretations, location rankings and travel recommendations. The generalized coastline is not for navigation, geocoding, timezone resolution or local eclipse maps. No uploaded SVG, image, URL, font or markup enters the renderer.

{"at":{"date":"2026-09-23","time":"12:00","timezone":"UTC"},"bodies":["sun","moon","venus"],"include_geojson":true,"include_geojson_seq":true,"include_ndjson":true,"include_topojson":true,"include_kml":true,"include_gpx":true,"include_csv":true,"include_wkt":true,"include_wkb":true,"include_gml":true,"include_svg":true,"include_png":true,"theme":"dark"}

Global eclipse geometry

POST /api/astro/eclipse-geometry searches a positive whole-second UTC interval of at most 366 days for selected solar and lunar eclipses. Solar events use bundled JPL DE421 Sun–Moon shadow-axis and cone geometry at the modeled global maximum; lunar events use Skyfield's Danjon shadow model. The response classifies solar events as partial, total, annular, or hybrid and lunar events as penumbral, partial, or total, with explicit geometry fields and at most twelve events.

Omitting observer preserves the exact global/geocentric response. Supplying strict WGS84 lat/lon adds one sea-level, no-refraction topocentric apparent snapshot at each event's rounded global maximum: eclipsed-body altitude, azimuth, angular radius, upper-limb horizon state and snapshot-only geometric visibility; solar events also include the Moon's altitude, azimuth, angular radius, disk separation and overlap.

The optional snapshot is not the location's maximum eclipse and does not calculate contacts, visibility at other instants, a geographic path or map, atmosphere, terrain, weather, lunar-limb effects, eye-safety guidance or interpretation. A false snapshot flag does not mean the eclipse is never visible at that location.

{"start_utc":"2024-01-01T00:00:00Z","end_utc":"2025-01-01T00:00:00Z","eclipse_types":["solar","lunar"],"observer":{"lat":25.286666667,"lon":-104.138333333}}

Bounded electional search

POST /api/astro/electional-search evaluates an AND-only filter set on a fixed hourly UTC grid over a positive interval of at most seven days and 168 samples. Filters can select Moon signs, eight Moon-phase sectors, direct or retrograde Mercury, Ascendant signs, and up to four Sun-through-Pluto major-aspect conditions. A location is required; tropical is the default, while sidereal supports Lahiri, Raman, Krishnamurti, Fagan–Bradley, Yukteshwar, Sassanian, True Chitra, True Revati, True Pushya, Galactic Center at 0 Sagittarius, and Galactic Alignment/Mardyks.

Returned samples and grouped windows describe only the evaluated hourly grid. They are not continuous guarantees, rankings, recommendations, void-of-course analysis, a boundary solver, or interpretation. Exact geographic poles are rejected.

{"start_utc":"2026-09-23T00:00:00Z","end_utc":"2026-09-24T00:00:00Z","location":{"lat":40.7128,"lon":-74.006},"filters":{"moon_signs":["Aquarius","Pisces"],"mercury_motion":"direct"}}

Live electional reliability beta: R231 extends sampled electional evidence with exact repair-hardening minimax regret across uncertain failure budgets. It is part of the 78 live calculations. Read the electional reliability guide for its method, bounds, response evidence, and limitations.

Natal aspect analysis

POST /api/astro/natal-analysis calculates apparent geocentric longitudes for 3–10 explicitly selected Sun-through-Pluto points, then returns every configured aspect within its inclusive orb. Use the neutral aspect_profile value major, standard, or extended, or send a mutually exclusive custom aspects list. The eleven available definitions include the five major aspects plus semisextile, semisquare, quintile, sesquiquadrate, biquintile, and quincunx; each custom aspect has its own 0.1°–10.0° orb. Omit both selectors for the existing standard six-aspect default.

An optional additional_points array accepts one through six unique values: vertex, antivertex, equatorial_ascendant, equatorial_descendant, lot_of_fortune, and lot_of_spirit. They are returned in a separate object with explicit geometry, sect, formula and frame metadata. They do not silently join planetary aspects, midpoints or patterns; omission preserves the existing response shape.

Optional midpoint output provides both antipodal axes for each point pair. Optional pattern detection reports only exact geometric matches for Grand Trines, T-squares, Grand Crosses, and Yods under the supplied aspect definitions and orbs. It does not interpret a chart, infer personality, rank patterns, or provide advice.

{"birth":{"date":"2000-01-01","time":"12:00","timezone":"UTC","lat":40.7128,"lon":-74.006},"points":["sun","moon","mercury","venus","mars","jupiter","saturn"],"aspect_profile":"extended","additional_points":["vertex","equatorial_ascendant","lot_of_fortune","lot_of_spirit"],"include_midpoints":true,"include_patterns":true}

Opt-in Parashari graha drishti

Set strict include_graha_drishti: true only with explicit zodiac: "sidereal". The response adds seven classical-graha rows under the named parashari_whole_sign_full_aspects_v1 ruleset: every graha receives a seventh-house full aspect, Mars also receives fourth/eighth, Jupiter fifth/ninth, and Saturn third/tenth. Signs are counted inclusively from each source sign using unrounded Lahiri or another explicitly selected supported sidereal longitude.

{"birth":{"date":"1990-01-01","time":"12:00","timezone":"UTC","lat":40.7128,"lon":-74.006},"points":["sun","moon","mercury"],"zodiac":"sidereal","ayanamsa":"lahiri","include_graha_drishti":true}

Rahu and Ketu are excluded as sources and targets. The result contains full whole-sign aspects only: no partial strengths, orbs, dignity, yogas, interpretation, prediction, remedies, or claim that this convention represents every Jyotish lineage. Omission preserves the predecessor natal-analysis response. The ruleset remains beta pending fresh practitioner review.

Planetary hours

POST /api/astro/planetary-hours finds local sunrise, sunset, and the following sunrise, splits daylight and nighttime into twelve equal temporal intervals each, and assigns rulers in Chaldean order beginning with the ruler of the civil weekday. Because these are temporal hours, their duration changes with season and latitude.

Solar events use the existing apparent DE421 solar center and a fixed −50 arcminute horizon. The endpoint requires an IANA timezone and coordinates. A date that does not have exactly one ordered sunrise, sunset, and following sunrise is rejected; there is no polar fallback, electional ranking, interpretation, or advice. Supported dates end at 2050-12-30 because the calculation must obtain the following sunrise.

{"date":"2026-09-23","timezone":"America/New_York","lat":40.7128,"lon":-74.006}

Node.js 22+ example

Run this server-side with COSMICEPHEMERIS_KEY in the process environment. Never expose the key in browser code.

const key = process.env.COSMICEPHEMERIS_KEY;
if (!key) throw new Error("Set COSMICEPHEMERIS_KEY");
const response = await fetch("https://api.cosmicephemeris.com/api/astro/fixed-stars", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
    Accept: "application/json"
  },
  body: JSON.stringify({
    at: {date: "2026-09-23", time: "12:00", timezone: "UTC"},
    stars: ["aldebaran", "regulus", "sirius"]
  }),
  signal: AbortSignal.timeout(20000)
});
if (!response.ok) throw new Error(`Cosmic Ephemeris returned ${response.status}`);
console.log(await response.json());

Clients and complete schemas

The Node client methods are eventCalendar, synastrySvg, transitSvg, natalReport, birthTimeSensitivity, fixedStars, relocationChart, astrocartography, eclipseGeometry, electionalSearch, natalAnalysis, and planetaryHours. Python uses the matching snake-case names. Request and response schemas, errors, limits, and examples are in the OpenAPI JSON; runnable examples are in the Postman collection.