Meanings with clear boundaries
Readings, Tarot & Structured Horoscope
Build symbolic readings, Tarot experiences and structured horoscope features in your own application. These distinct API products have different response contracts.
Three APIs, clearly separated
Symbolic readings return prose and calculation evidence. Tarot returns card draws and symbolic meanings. The structured horoscope API returns rule-based fields, not reading prose. None calls an external AI provider at generation time.
Symbolic readings API
The Readings provides birth-chart reflections, Western synastry and Vedic Ashtakoota explanations, Pythagorean numerology, and sampled daily/weekly/annual themes in English, Hindi and Spanish. All prose and translations are AI-assisted. The dashboard interface and technical calculation labels remain English.
These are symbolic reflections, not scientific predictions. Birth profiles and explicit historical transit samples support 1000 BCE (BC)–2500 CE (AD). Historical samples use noon UT1 with an explicitly selected proleptic Gregorian or Julian calendar; standard date strings retain 1800–2200 and noon UTC. Every sample must remain in range. Historical numerology requires a year-digit convention; Vedic matching requires both profiles to use the same historical or standard time mode. Whole-sign houses are used for symbolic readings.
Each admitted API attempt uses one standard calculation credit, including failed calculations. Responses contain the result, evidence, disclosures and version; your application renders and stores them. The website no longer provides a saved-reading history screen. Existing stored records are retained; this interface change does not delete account data. Guided explanations are preset answers grounded in the result, not an external AI model.
The Saved Readings website screen has been retired; existing records and session API compatibility are retained. New on-site generation has been removed. Stateless generation is available through the supplemental HTTP endpoints and the separate MCP symbolic tool; published Node/Python 0.5.0 adds matching methods. The structured horoscope endpoint below still returns fields, not this prose.
Reading content version 1.2.0 introduced Vedic Moon nakshatra/pada, planetary D9/Navamsa themes and the birth Yogini period, each linked to its calculation. Western aspects retain planet-specific explanations and measured orbs; compatibility and transit roles remain explicit. These are bounded symbolic models, not marriage predictions or a complete strength analysis.
Current reading content version is 1.2.1. It updates the AI-assisted symbolic-use disclosure without changing calculations or interpretation meanings. Existing saved JSON, content versions and fingerprints remain unchanged; older disclosure wording is updated only for on-screen and PDF display, with a notice.
Integrate your first reading
- Create a server-side API key with
astro:symbolic-readingscope. - Send the birth inputs, reading kind, language and applicable tradition to
POST /api/symbolic/symbolic-reading. - Render the returned text and evidence in your application, preserving disclosures and version metadata.
Tarot API: all 78 cards
The Tarot returns original Cosmic Symbols cards in English, Spanish and Hindi, upright/reversed meanings, daily mode and single-card, three-card or Celtic Cross spreads. Text and translated adaptations are AI-assisted. Your application owns the interface; the website does not offer card draws.
Use a server-side key with astro:tarot scope or astro:*. Each admitted attempt uses one standard credit. Daily mode shares a card across languages for each UTC date and deck version. No external AI call is made. Results are stateless and are not saved to account history. Your application owns the presentation, storage and exports.
Supplemental readings API
Use POST /api/symbolic/tarot, POST /api/symbolic/symbolic-reading or POST /api/symbolic/vedic-systems with a server-side API key. Each requires its matching astro:tarot, astro:symbolic-reading, astro:vedic-systems scope or astro:*, and uses one standard credit per admitted attempt, including failed calculations. Existing plan and key budgets apply. These calls are stateless: they do not save to an account.
POST /api/symbolic/tarot
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{"locale":"es","options":{"spread":"three","theme":"relationship","reversals":true,"mode":"draw"}}
Download the supplemental OpenAPI contract. Use these routes directly or through cosmicephemeris_symbolic on MCP. Node/Python 0.5.0 adds tarot, symbolicReading/symbolic_reading, and vedicSystems/vedic_systems; 0.5.0 is published on npm and PyPI. Batch jobs and signed receipts are not added. Account PDF download uses the signed-in session at GET /api/readings/:id/pdf, not an API key.
Vedic systems and regional calendar factors
The Vedic-systems request contains birth, an explicit ayanamsa, and system: yogini, birth_factors, or regional_calendars. Yogini returns an eight-period, 36-year cycle with proportional subperiods using fixed 365.25-day years. Birth factors add Moon nakshatra/pada and D9 mappings.
Regional factors provide the Indian national/Saka civil date, Amanta lunar-month factors, and ordinary Purnimanta month labels. Intercalation that requires a regional rule returns an explicit unresolved status rather than a guessed Purnimanta label. This is not a complete festival calendar, historical reconstruction, or sunrise-day allocation. Proleptic Saka years before adoption are explicitly marked; ancient precision remains uncertain.
Named North/South festival calendars
Choose system: "festival_calendar", region: "north_purnimanta" or "south_amanta", explicit ayanamsa: "lahiri", and days: 1..31. Supply the starting local date, timezone and coordinates in birth. Its time is validated but calendar days use local sunrise, not that birth time.
Eighteen named observances per preset. The original seven are North Chaitra Navratri start or South Ugadi; Rama Navami, Akshaya Tritiya, Guru Purnima, Ganesh Chaturthi, Sharad Navratri start and Vijayadashami. The expanded list adds Vasant Panchami, Ratha Saptami, Maha Shivaratri, Buddha Purnima (Vaishakha full moon), Dhanteras, Diwali/Lakshmi Puja, Bhai Dooj and Kartik Purnima. Three further rules cover Holika Dahan, next-day Holi and Raksha Bandhan, subject to the Bhadra limits below.
The eight earlier additions require one qualifying day: sunrise for Ratha Saptami and the two Purnimas, forenoon for Vasant Panchami, afternoon for Bhai Dooj, evening Pradosha for Dhanteras/Diwali and overnight Nishita for Maha Shivaratri. Pradosha is the first fifth of sunset to the next sunrise; Nishita is the middle fifteenth. A night belongs to its sunset date, including windows after midnight. These windows are calculation evidence, not ritual muhurtas.
Holika Dahan prefers a unique Bhadra-free Pradosha; its declared fallback is after Bhadra and before Hindu midnight (the midpoint of sunset to next sunrise), with Purnima present in that evening’s Pradosha. Raksha Bandhan prefers Bhadra-free Aparahna, then Pradosha. Bhadra ends at the solved 174-degree Moon–Sun elongation, not the arithmetic midpoint of the tithi duration. Output includes clipped governing windows and bhadra evidence. Holi is the following local civil day only after Holika is resolved: its derived result uses source_observance and an offset rule, not its own governing-window/tithi timestamps. A source day can be outside the requested page.
Read unresolved_observances as well as festivals. Multiple qualifying days, absent windows or unavailable solar geometry are flagged instead of assigned an invented date. For example, Delhi's 2025 Diwali has October 20 and 21 as candidates under the declared Pradosha rule. Diagnostics can repeat across adjoining pages; selected festival dates stay inside each requested page.
The original seven retain their existing policy: repeated sunrise tithis choose the earlier day; skipped sunrise uses greatest daylight overlap; midday/afternoon rules choose greatest window overlap with earlier ties. Annual rules exclude adhika months. Kshaya, Purnimanta intercalation and unusable polar solar anchors remain flagged. Historical results are proleptic, not evidence of historical observance.
metadata.coverage makes the limits machine-readable. This is not a complete regional calendar: Janmashtami, Ekadashi/parana, solar-ingress and local temple festivals remain excluded. Holika Bhadra-tail/face and Raksha Bandhan overnight exceptions are not implemented; unsupported cases remain unresolved. All sectarian tie-breaks, ritual muhurtas and universal Vesak dates are not claimed.
Structured Horoscope API
Standard examples below use 1800–2200 civil dates. Explicit historical inputs cover 1000 BCE–2500 CE under the historical contract; calendar, time convention and per-tool bounds remain required.
This current endpoint compares a natal chart with one transit instant and returns deterministic interpretation fields that your application can render in its own voice.
Endpoint
POST https://api.cosmicephemeris.com/api/astro/horoscope
Authenticate with Authorization: Bearer <API_KEY> from your server.
Request fields
birth.date,birth.time,birth.lat, andbirth.lonare required.birth.timezoneaccepts an IANA name and defaults toUTC.transitDatedefaults to the current UTC date.transitTimedefaults to12:00; top-leveltimezonedefaults toUTC.zodiacdefaults totropical. In sidereal mode,ayanamsadefaults tolahiri.
Times must use HH:MM or HH:MM:SS. A local time that is
skipped or repeated during a daylight-saving or other clock change returns
400; send the known UTC date and time with timezone: "UTC"
to identify the intended instant without guessing an hour.
Example request
{
"birth": {
"date": "1990-01-01",
"time": "12:00",
"timezone": "America/New_York",
"lat": 40.7128,
"lon": -74.006
},
"transitDate": "2025-01-01",
"transitTime": "12:00",
"timezone": "America/New_York"
}
Response shape
The following is abbreviated from the request above. Signal values depend on the requested instants.
{
"type": "horoscope",
"input": {
"birth": { "...": "submitted birth fields" },
"transitDate": "2025-01-01",
"zodiac": "tropical",
"ayanamsa": "lahiri"
},
"interpretation": {
"summary": {
"overall_tone": "challenging",
"intensity": 0.88
},
"transits": [
{
"planet": "Sun",
"planet_nature": "luminary",
"planet_sect": "day",
"chart_sect": "day",
"aspect": "Conjunction",
"natal_point": "Sun",
"house": null,
"house_topics": [],
"tone": "intensifying",
"intensity": 1,
"tradition": ["hellenistic", "western"],
"summary_key": "sun_conjunction_sun"
}
]
}
}
Current limits
- The standard date-string calculation window is
1800-01-01through2200-12-31. - The rules emit structured signals only; your product owns prose and editorial meaning.
chart_sectis calculated from the natal location and instant: day when the apparent Sun's center is above the geometric horizon, night otherwise. The calculation uses zero elevation and no atmospheric refraction; it is not a sunrise/sunset timetable.- House attribution is outside the current contract; the field returns
null. - This is a standard billable endpoint under the account's monthly request quota.
Errors
400invalid fields, timezone, zodiac, ayanamsa, or date range401missing or invalid API key429monthly quota or edge rate limit reached502calculation engine unavailable;504calculation timed out503service concurrency limit; retry according toRetry-Afterwhen present