A JSON HTTP API over the Jagannatha Hora calculation engine. Send a birth date, time and place; get back the full Vedic chart — 23 divisional charts, dashas, yogas, doshas, ashtakavarga, transits, panchang, muhurta and compatibility. 15 endpoints, all open with no API key.
Start here
The API is live at https://jagannatha-hora-359167915530.europe-west1.run.app. There is nothing to sign up for. Send a POST with a JSON body and read the JSON that comes back. This one command returns a complete Vedic birth chart:
If you do not know the coordinates for a birth place, resolve it first with GET /location/search, which searches an index of more than 162,000 cities and returns latitude, longitude and the timezone offset. That is the normal two-step flow: one lookup, then one calculation.
If you are wiring this into an AI agent rather than an application, use the MCP server instead. It exposes the same engine as 33 individually callable tools, so a model can ask for just the dashas or just the ashtakavarga and get kilobytes back rather than the megabytes /horoscope returns.
Machine-readable versions of this page
This page exists in three more formats, with the same facts.
horoscopes.today/openapi.json — OpenAPI 3.1 description of every endpoint below. Point a code generator, an HTTP client or an agent at this rather than parsing prose.
horoscopes.today/api.md — This entire reference as plain Markdown, for LLM fetchers and anything else that would rather not strip HTML.
Every endpoint is open — no key, no token, no signup. CORS is open too, so browser-side calls work.
Rate limits
Each POST endpoint has its own per-minute limit, listed with the endpoint below and counted per client IP address (an IPv6 client is counted by its /64 network). The GET endpoints are not rate limited. Over the limit, the response is 429 with the body {"error": "Rate limit exceeded: 30 per 1 minute"}. The MCP server allows 30 requests a minute per IP.
Same inputs, same output
These are astronomical calculations, not model inferences: the same inputs give the same output until the calculation engine changes. /horoscope and /marriage-match return engine_revision, an integer that goes up whenever calculated values change, so cache by input and engine_revision. The exception is /saturn-timeline, whose current phase and months remaining are measured from today's date. /panchang, /gochar and /gochar/events also send Cache-Control: public, max-age=21600.
Dates, times and time zones
Dates are YYYY-MM-DD and times are HH:MM:SS on a 24-hour clock, always as strings. Time zones are a decimal hour offset from UTC (5.5, not "Asia/Kolkata"). /horoscope, /gochara and /surya-siddhanta work out the historically correct birth offset, daylight saving included, from the coordinates and date unless you send timezone_mode "file"; /marriage-match, /gochara/range and /muhurta always do. /panchang, /gochar, /gochar/events and every event_timezone are worked out from the coordinates the same way. In all of these your value is the fallback where no time zone is known for the place. /saturn-timeline and /planet-ingress use the offset exactly as you send it.
Responses are gzipped
Responses over 1 KB are gzip-compressed. This matters most for /horoscope, where it turns megabytes into hundreds of kilobytes. Send Accept-Encoding: gzip — every common HTTP client does by default.
Two kinds of input error
A missing, mistyped or out-of-range field, or a value outside an allowed list, is a 422 whose detail lists each problem with the field's location. A well-formed request the calculation cannot serve — a range that is too long, an unknown planet — is a 400 with a message. Either way the detail names the field and the limit, so it is worth showing to your users.
The shared birth-details block
Seven endpoints take a birth chart as their subject: /horoscope, /surya-siddhanta, /marriage-match (two of them), /gochara, /gochara/range, /muhurta and /saturn-timeline. The two blocks of fields most of them share are listed once here rather than repeated below.
POST /horoscope takes the full block below: six required fields, then calculation settings that all have defaults and that you can ignore until you need them.
Birth details and calculation settings for POST /horoscope
Parameter
Type
Required
Default
Notes
date
string
Yes
—
Birth date, YYYY-MM-DD. Year 1800-2100, month 1-12, day 1-31.
time
string
Yes
—
Birth time, HH:MM:SS (24-hour). Hour 0-23, minute 0-59, second 0-59.
place
string
Yes
—
Birth place name, echoed in the response. The coordinates decide the calculation.
latitude
number
Yes
—
Decimal degrees, -90 to 90, north positive. Birth places beyond about 66.5° north or south (inside the polar circles) are rejected with 422.
longitude
number
Yes
—
Decimal degrees, -180 to 180, east positive.
timezone
number
Yes
—
UTC offset in hours, -12 to 14 (5.5 for IST). By default the API works out the historically correct offset, daylight saving included, from the coordinates and date, and uses this value only where no time zone is known for the place. See timezone_mode.
elevation
number
No
0.0
Metres above sea level.
gender
string
No
null
"male" or "female" ("m" and "f" also work). A few classical yogas depend on gender; when it is omitted they are left out of the yoga list rather than guessed. Any other value is rejected with 422.
ayanamsa_mode
string
No
"LAHIRI"
One of the 20 listed modes, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. SIDM_USER needs ayanamsa_value. Any other value is rejected with 422.
ayanamsa_value
number
No
null
Your own ayanamsa in degrees, -30.0 to 30.0, used with ayanamsa_mode SIDM_USER. SIDM_USER without a value is rejected with 422.
calculation_type
string
No
"drik"
"drik" (modern positions) or "ss" (Surya Siddhanta). Case-insensitive. With "ss" the chart also carries a surya_siddhanta section.
node_type
string
No
"mean"
Rahu/Ketu as the "mean" or the "true" lunar node. Any value other than "true" gives the mean node.
bhava_madhya_method
integer
No
1
House system for bhava_chart, 1-5: 1 = equal houses with the lagna at the middle, 2 = equal houses with the lagna at the start, 3 = Sripati, 4 = KP (houses start at the Placidus cusps), 5 = whole sign. Whatever the method, bhava_chart's 12 slots are arranged by sign (slot 0 = Aries), with house 1 in the slot of the lagna's sign.
timezone_mode
string
No
"auto"
"auto" works out the historical offset from the coordinates and date, falling back to timezone where no zone is known; "file" uses timezone exactly as sent. Either way birth_details in the response reports timezone_used, timezone_derived and timezone_source. Any other value is rejected with 422.
language
string
No
"en"
Language for names in the response: en, hi, ka, ta or te.
Sixty-hour period number for hora progressions, 1-1000.
divisional_chart_factor
integer
No
1
1-300. Names the divisional chart that chart_method applies to (1 = D-1, 9 = D-9 and so on). It does not select which charts come back: divisional_charts always holds all 23. A factor that is not one of those 23 is reported in request_notes.
chart_method
integer
No
1
1-6. Construction method for the chart named by divisional_chart_factor; how many methods exist depends on the chart (D-1 has one, D-9 five, D-2 six). An unavailable method falls back to 1 and is reported in request_notes.
base_rasi
integer
No
null
0-11 (0 = Aries). Applies only to custom divisional charts, which this endpoint does not return; if set, it is reported in request_notes and otherwise has no effect.
count_from_end_of_sign
boolean
No
null
Applies only to custom divisional charts, which this endpoint does not return; if set, it is reported in request_notes and otherwise has no effect.
varnada_method
integer
No
1
Method for the varnada outputs (house_varnadas, the Varnada entries in amsa_rulers and the Varnada dasha): methods 1 to 4. A higher value falls back to 1 and is reported in request_notes; a negative value is rejected with 422.
tamil_month_method
integer
No
3
How the Tamil solar month is reckoned: 0, 1, 2 or 3. 1 starts the month at sunset, 2 at 10 AM, 3 at midday UTC.
kali_start_year
integer
No
13
Naming of the sixty-year cycle: 1 starts at Prabhava (South Indian), 13 at Pramaadhi (North Indian).
The natal block
POST /gochara, POST /gochara/range and POST /muhurta take this smaller block for the birth chart, plus their own fields listed with each endpoint. They take none of the other calculation settings above; /gochara adds node_type and timezone_mode. /saturn-timeline, /surya-siddhanta and /marriage-match list all their own fields.
Birth details for POST /gochara, POST /gochara/range and POST /muhurta
Parameter
Type
Required
Default
Notes
date
string
Yes
—
Birth date, YYYY-MM-DD. Year 1800-2100.
time
string
Yes
—
Birth time, HH:MM:SS (24-hour).
place
string
No
""
Birth place name, echoed in the response. The coordinates decide the calculation.
latitude
number
Yes
—
Decimal degrees, -90 to 90. Birth places beyond about 66.5° north or south (inside the polar circles) are rejected with 422.
longitude
number
Yes
—
Decimal degrees, -180 to 180.
timezone
number
Yes
—
UTC offset at birth in hours, -12 to 14. The API works out the historically correct offset, daylight saving included, from the coordinates and date, and uses this value only where no time zone is known for the place.
elevation
number
No
0.0
Metres above sea level.
ayanamsa_mode
string
No
"LAHIRI"
One of the listed modes except SIDM_USER, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. Any other value is rejected with 422, SIDM_USER included, since no ayanamsa_value is taken here.
LAHIRI is the default and the most widely used in Indian practice. The choice shifts every sidereal longitude, so pick one and stay with it. Names are case-insensitive, and KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI. SIDM_USER uses your ayanamsa_value and needs it; only /horoscope and /surya-siddhanta take one. Every endpoint rejects any other value with 422 and a message listing the accepted modes; it is never replaced by LAHIRI. /saturn-timeline accepts LAHIRI or RAMAN only.
All 15 endpoints
Listed most useful first. Every one of them returns JSON.
POST/horoscope
The complete Vedic birth chart for a birth moment.
The workhorse endpoint. One call returns every calculation the engine performs for a chart: 23 divisional charts, nakshatras and padas, yogas, doshas, chara karakas, sahams, upagrahas, special lagnas, sphutas, arudhas, house relationships, planetary states, Shad Bala and the other strengths, ashtakavarga, graha and rasi dashas, Saturn transits and longevity reference computations. The response is large — several megabytes of JSON — and gzip-compressed on the wire, so cache it on your side.
birth_details echoes your input plus timezone_used, timezone_derived and timezone_source (the offset actually applied and where it came from) and request_settings (every calculation setting the chart was computed with).
engine_revision is an integer that goes up whenever calculated values change. The same inputs return the same chart until it changes, so cache by input and engine_revision.
divisional_charts always holds all 23 vargas; divisional_chart_factor only names the chart chart_method applies to.
If you only need one slice — the dashas, the ashtakavarga, the yogas — the MCP server exposes each as its own tool and returns kilobytes instead of megabytes.
POST/surya-siddhanta
A natal chart computed by the classical Surya Siddhanta method.
Surya Siddhanta positions for a birth moment: the lagna, the nine bodies with sign, degree, nakshatra and pada, daily motion and retrograde flag, and the Surya Siddhanta panchanga (tithi, nakshatra, yoga, karana, vaara, sunrise and sunset). The ayanamsa block reports the Surya Siddhanta ayanamsa and its difference from the mode you ask for; positions are expressed in that requested ayanamsa. Names are always in English. Every other endpoint uses modern (drik) positions.
Rate limit
60 requests/minute per IP
Authentication
None. Open endpoint, no key required.
Response keys
birth_details, surya_siddhanta
Body fields for /surya-siddhanta
Parameter
Type
Required
Default
Notes
date
string
Yes
—
Birth date, YYYY-MM-DD; must be a real calendar date. Year 1800-2100.
time
string
Yes
—
Birth time, HH:MM:SS (24-hour).
latitude
number
Yes
—
Decimal degrees, -90 to 90. Places beyond 66° north or south are rejected with 400.
longitude
number
Yes
—
Decimal degrees, -180 to 180.
timezone
number
Yes
—
UTC offset at birth in hours, -12 to 14. By default the API works out the historically correct offset, daylight saving included, from the coordinates and date, and uses this value only where no time zone is known for the place. See timezone_mode.
place
string
No
""
Place name, echoed in the response.
elevation
number
No
0.0
Metres above sea level. Echoed in the response only.
timezone_mode
string
No
"auto"
"auto" works out the offset from the coordinates and date; "file" uses timezone exactly as sent. Any other value is rejected with 422.
ayanamsa_mode
string
No
"LAHIRI"
The ayanamsa the positions are expressed in and the Surya Siddhanta ayanamsa is compared against. One of the 20 listed modes, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. SIDM_USER needs ayanamsa_value. Any other value is rejected with 422.
ayanamsa_value
number
No
null
Your own ayanamsa in degrees, -30.0 to 30.0, used with ayanamsa_mode SIDM_USER. SIDM_USER without a value is rejected with 422.
surya_siddhanta holds method, epoch, ayanamsa, lagna, planets and panchanga.
The same chart is available inside POST /horoscope as horoscope.surya_siddhanta when you send calculation_type "ss".
POST/marriage-match
Ashtakoota (North Indian) and 10 Porutham (South Indian) compatibility for two charts.
Takes two birth charts and scores them under both classical systems at once, then adds the dosha scores for each person and the Beeja and Kshetra rasi. The North Indian block scores the eight kootas out of 36 and adds four further poruthams; the South Indian block reports each of the ten poruthams as matched or not, with the minimum-porutham flag. Each block also carries the classical rating band for its score (for example "Good" or "Poor"); it is a score band, not advice.
date, time, latitude, longitude and timezone (all required) and elevation (default 0.0). No place field and no calculation settings.
girl_birth_details
object
Yes
—
Same shape as boy_birth_details.
Fields of each person object in /marriage-match
Parameter
Type
Required
Default
Notes
date
string
Yes
—
Birth date, YYYY-MM-DD. Year 1800-2100.
time
string
Yes
—
Birth time, HH:MM:SS (24-hour).
latitude
number
Yes
—
-90 to 90. Birth places beyond about 66.5° north or south (inside the polar circles) are rejected with 422.
longitude
number
Yes
—
-180 to 180.
timezone
number
Yes
—
UTC offset at birth in hours, -12 to 14. The API works out the historically correct offset, daylight saving included, from the coordinates and date, and uses this value only where no time zone is known for the place.
The full daily panchang for a date and place. No birth chart needed.
The five limbs — vaara, tithi, nakshatra, yoga, karana — with paksha, plus sun and moon rise and set, day length, the auspicious and inauspicious windows, day and night Choghadiya, the lunar month in both Amanta and Purnimanta reckoning, ritu, ayana, the Shaka, Vikrama and Kali years with the sixty-year cycle name, and the Moon and Sun signs. The response carries Cache-Control: public, max-age=21600.
Rate limit
60 requests/minute per IP
Authentication
None. Open endpoint, no key required.
Response keys
panchang
Body fields for /panchang
Parameter
Type
Required
Default
Notes
date
string
Yes
—
YYYY-MM-DD; must be a real calendar date (2026-02-31 is rejected). Year 1800-2100.
latitude
number
Yes
—
-90 to 90. Places beyond 66° north or south are rejected with 422, as is a date on which the Sun does not rise or set at the place.
longitude
number
Yes
—
-180 to 180.
timezone
number
Yes
—
UTC offset in hours, -12 to 14. The API works out the historically correct offset, daylight saving included, from the coordinates and date, and uses this value only where no time zone is known for the place.
place
string
No
""
Place name, echoed in the response as place.name.
ayanamsa_mode
string
No
"LAHIRI"
One of the listed modes except SIDM_USER, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. Any other value is rejected with 422, SIDM_USER included, since no ayanamsa_value is taken here.
Rahu Kalam is under inauspicious.rahu_kalam and the Abhijit muhurta under auspicious.abhijit_muhurta. Times are local to the place; "(+1d)" marks a time on the next day.
POST/gochar
Planetary positions for a date and place. No birth chart needed.
The nine grahas with sign and degree, nakshatra and pada, retrograde and combust flags, classical dignity (exalted, debilitated, moolatrikona, own, or null), speed in degrees per day, and when each next changes sign, nakshatra and pada — plus highlights with the Moon and Sun signs and the planets currently retrograde. Positions are geocentric and so the same worldwide at an instant; the place's timezone decides what counts as that date and how the times are shown. The response carries Cache-Control: public, max-age=21600.
Rate limit
60 requests/minute per IP
Authentication
None. Open endpoint, no key required.
Response keys
gochar
Body fields for /gochar
Parameter
Type
Required
Default
Notes
date
string
Yes
—
YYYY-MM-DD; must be a real calendar date. Year 1800-2100.
latitude
number
Yes
—
-90 to 90. No polar restriction.
longitude
number
Yes
—
-180 to 180.
timezone
number
Yes
—
UTC offset in hours, -12 to 14. The API works out the historically correct offset, daylight saving included, from the coordinates and date, and uses this value only where no time zone is known for the place.
place
string
No
""
Place name, echoed in the response as place.name.
ayanamsa_mode
string
No
"LAHIRI"
One of the listed modes except SIDM_USER, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. Any other value is rejected with 422, SIDM_USER included, since no ayanamsa_value is taken here.
sign_until, nakshatra_until and pada_until are local date-times, "YYYY-MM-DD HH:MM".
POST/gochar/events
Transit events over a date range. No birth chart needed.
One date-sorted list of sign changes for every requested planet, nakshatra changes for all of them except the Moon (which changes nakshatra roughly daily), and retrograde stations for Mars, Mercury, Jupiter, Venus and Saturn. Each event has a type — "sign", "nakshatra" or "retrograde" — and a local date-time; sign and nakshatra events carry from, to and direction, and stations carry motion ("turns_retrograde" or "turns_direct"). The response carries Cache-Control: public, max-age=21600.
Rate limit
60 requests/minute per IP
Authentication
None. Open endpoint, no key required.
Response keys
gochar_events
Body fields for /gochar/events
Parameter
Type
Required
Default
Notes
from_date
string
Yes
—
Range start, YYYY-MM-DD; a real calendar date.
to_date
string
Yes
—
Range end, YYYY-MM-DD. Must be after from_date and at most 90 days later, or the response is 400.
latitude
number
Yes
—
-90 to 90. Used for the display timezone.
longitude
number
Yes
—
-180 to 180.
timezone
number
Yes
—
UTC offset in hours, -12 to 14, for expressing event times. The API works out the offset from the coordinates where it can; this value is the fallback.
place
string
No
""
Place name. Not used in the calculation.
planets
string[]
No
null
Planet names. Defaults to all nine: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu. An unknown name is a 400.
ayanamsa_mode
string
No
"LAHIRI"
One of the listed modes except SIDM_USER, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. Any other value is rejected with 422, SIDM_USER included, since no ayanamsa_value is taken here.
Transits for one target date, read against a birth chart.
The natal counterpart to /gochar. Returns the target moment and place, a short natal reference (Moon and lagna), the panchanga for the target moment, the muhurta windows (sunrise, sunset, solar noon, Abhijit with its clean sub-windows, and the Rahu, Gulika and Yamaganda periods), all nine planets with their house from the natal Moon and Lagna, and the person-relative strengths — Tara Bala from Moon, Sun and Lagna, Chandra Bala and Sade Sati state. The optional sections add ashtakavarga bindus and gochara-phala with vedha to each planet, and the D-1 and D-9 transit charts. The event location defaults to the birth location.
Rahu/Ketu as the "mean" or "true" node. Any value other than "true" gives the mean node.
timezone_mode
string
No
"auto"
"auto" works out the birth offset from the coordinates and date; "file" uses the birth timezone exactly as sent. Any other value is rejected with 422.
target_date
string
Yes
—
The date to read transits for, YYYY-MM-DD. Year 1800-2100.
target_time
string
No
"12:00:00"
HH:MM:SS on the target date. Defaults to local noon.
event_place
string
No
null
Name of the place the transits are read for. Defaults to the birth place.
event_latitude
number
No
null
-90 to 90. Defaults to the birth latitude. A date on which the Sun does not rise or set at the place is rejected with 422.
event_longitude
number
No
null
-180 to 180. Defaults to the birth longitude.
event_timezone
number
No
null
-12 to 14. The API works out the offset from the event coordinates where it can; this value, or the birth timezone when it is omitted, is the fallback.
event_elevation
number
No
null
Metres. Defaults to the birth elevation.
include
string[]
No
null
Optional sections: "ashtakavarga", "gochara_phala", "transit_charts". Omit the field for all three; pass [] for none, or a subset.
The same natal transit reading for every day in a range, in one call.
Built for the case where an AI agent should do the deciding. Returns, for each day, the panchanga, muhurta windows including the clean Abhijit, the nine planets with their house from the natal Moon and Lagna, and the person-relative strengths — with no scoring and no "best date" verdict, so the caller reasons over the raw data itself. Ashtakavarga bindus and gochara-phala with vedha are added to each planet unless you leave them out. Rahu and Ketu are always the mean node here.
Last day, YYYY-MM-DD. At most 60 days counting both ends, and not before from_date, or the response is 400.
time_of_day
string
No
"12:00:00"
HH:MM:SS used on each day. Defaults to local noon.
event_place
string
No
null
Name of the place the transits are read for. Defaults to the birth place.
event_latitude
number
No
null
-90 to 90. Defaults to the birth latitude. A date on which the Sun does not rise or set at the place is rejected with 422.
event_longitude
number
No
null
-180 to 180. Defaults to the birth longitude.
event_timezone
number
No
null
-12 to 14. The API works out the offset from the event coordinates where it can; this value, or the birth timezone when it is omitted, is the fallback.
event_elevation
number
No
null
Metres. Defaults to the birth elevation.
include
string[]
No
null
Optional sections per day: "ashtakavarga" and "gochara_phala". Omit the field for both; pass [] for the lean snapshot.
Pass include: [] when you want the lean snapshot. Omitting the field is not the same thing: it gives you both optional sections.
POST/saturn-timeline
Sade Sati and Dhaiyya timing, with the classical relief share.
Returns the Moon sign, the Sade Sati cycle that is running today (or else the next one, or the most recent), its three phases, whether it is active and which phase today falls in, the months remaining, and — from Saturn's kakshya in the ashtakavarga — the classical relief share. dhaiyya reports whether a 4th or 8th-house Saturn transit from the Moon is running today, and nextCycle the next Sade Sati. detail "full" adds the month-by-month bands, the interruptions and the segments. This is computation, not interpretation.
Rate limit
60 requests/minute per IP
Authentication
None. Open endpoint, no key required.
Response keys
saturn_timeline
Body fields for /saturn-timeline
Parameter
Type
Required
Default
Notes
date
string
Yes
—
Birth date, YYYY-MM-DD. Year 1800-2100.
time
string
Yes
—
Birth time, HH:MM:SS (24-hour).
place
string
No
""
Birth place name. Not used in the calculation.
latitude
number
Yes
—
-90 to 90. Birth places beyond about 66.5° north or south (inside the polar circles) are rejected with 422.
longitude
number
Yes
—
-180 to 180.
timezone
number
Yes
—
UTC offset at birth in hours, -12 to 14, used exactly as sent.
ayanamsa_mode
string
No
"LAHIRI"
"LAHIRI" or "RAMAN" only on this endpoint, case-insensitive; LAHARI is accepted for LAHIRI too. Anything else is rejected with 422.
detail
string
No
"summary"
"summary" or "full". Anything else is rejected with 422.
active, currentPhase, monthsRemaining, dhaiyya and which cycle is reported are worked out against today's date, so the same request gives a different answer over time. The example was computed on 2026-10-03.
moonSign is a sign name and moonDegree the Moon's sidereal longitude, 0-360.
POST/planet-ingress
Every sidereal sign change for a set of planets across a date range.
Includes retrograde back-outs and re-entries. Each crossing carries its local date-time ("YYYY-MM-DD HH:MM"), the signs it leaves and enters, a retrograde flag, a direction ("forward" or "retrograde"), and final_settling, which marks the last crossing of each sign boundary inside the window, so you can tell a temporary ingress from the one that sticks.
Rate limit
60 requests/minute per IP
Authentication
None. Open endpoint, no key required.
Response keys
planet_ingress
Body fields for /planet-ingress
Parameter
Type
Required
Default
Notes
planets
string[]
No
null
Planet names. Defaults to Saturn, Jupiter, Rahu and Ketu. An unknown name is a 400.
from_date
string
Yes
—
Range start, YYYY-MM-DD.
to_date
string
Yes
—
Range end, YYYY-MM-DD. Must be after from_date and at most about five years later (5 × 366 days), or the response is 400.
timezone
number
No
0.0
UTC offset in hours, -12 to 14, that crossing times are expressed in, used exactly as sent. Defaults to UTC, not IST.
ayanamsa_mode
string
No
"LAHIRI"
One of the listed modes except SIDM_USER, case-insensitive; KRISHNAMURTI, FAGAN_BRADLEY, SRI_YUKTESHWAR and LAHARI are accepted for KP, FAGAN, YUKTESHWAR and LAHIRI too. Any other value is rejected with 422, SIDM_USER included, since no ayanamsa_value is taken here.
timezone defaults to 0.0 (UTC). A crossing near local midnight will look like it is on the previous day unless you pass your own offset.
POST/muhurta
Score every day in a range for an event, against classical muhurta rules and the native's own chart.
Scores each day by the classical factors — vara, nakshatra, tithi, paksha — and by the person's strength on that day (Tara Bala, Chandra Bala, Sade Sati), per the rules for the chosen event type. Returns the rules applied, the weights used, and the days as candidates sorted by score, each with its factors, score and score_breakdown, any hard failures, the best windows (the clean Abhijit) and the Rahu, Gulika and Yamaganda windows to avoid. It ranks; it does not pick a date.
One of the six event types GET /muhurta/events lists. Any other value is rejected with 422.
from_date
string
Yes
—
Scan start, YYYY-MM-DD.
to_date
string
Yes
—
Scan end, YYYY-MM-DD. At most 90 days counting both ends, and not before from_date, or the response is 400.
event_place
string
No
null
Name of the place the transits are read for. Defaults to the birth place.
event_latitude
number
No
null
-90 to 90. Defaults to the birth latitude. A date on which the Sun does not rise or set at the place is rejected with 422.
event_longitude
number
No
null
-180 to 180. Defaults to the birth longitude.
event_timezone
number
No
null
-12 to 14. The API works out the offset from the event coordinates where it can; this value, or the birth timezone when it is omitted, is the fallback.
event_elevation
number
No
null
Metres. Defaults to the birth elevation.
day_part_resolution_minutes
integer
No
15
5 to 60; anything else is rejected with 422. Echoed in the response; it does not currently change the scoring, which reads each day at midday.
respect_inauspicious_windows
boolean
No
true
Report the Rahu, Gulika and Yamaganda windows to avoid.
The list of event_type values /muhurta accepts, each with a readable label and the classical basis of its rules. Today there are six: griha_pravesha_own, griha_pravesha_rented, travel_prayana, vehicle_purchase, business_shop_opening and property_purchase_registration.
Example response (abridged; comments mark the cuts)
{
"events": [
{
"event_type": "griha_pravesha_own",
"label": "Griha Pravesha (own / new house)"
},
{
"event_type": "griha_pravesha_rented",
"label": "Griha Pravesha (rented house)"
}
/* …4 more; each entry also has a source field */
]
}
Each entry has event_type, label and source.
GET/location/search
Resolve a place name to coordinates and a timezone offset.
Resolves against an index of more than 162,000 world cities and returns the single best match. For "City, Country" inputs that do not match directly, the trailing part is dropped and the search retried, so "Springfield, IL, US" falls back to "Springfield, IL". Use it to turn a typed birth place into the latitude, longitude and timezone the calculation endpoints need.
Rate limit
None (not rate limited)
Authentication
None. Open endpoint, no key required.
Response keys
place, latitude, longitude, timezone, source, country, displayName, state (when known)
Query parameters for /location/search
Parameter
Type
Required
Default
Notes
query
string
No
null
The place name, at least 2 characters after trimming. Send query or q; with neither, or under 2 characters, the response is 400.
timezone is the place's standard UTC offset (no daylight saving). The calculation endpoints work out historical, daylight-saving-aware offsets themselves where they can.
A miss is a 404 whose message suggests adding a country name or code.
The query is part of the URL. Send place names here, never birth dates or times.
GET/location/autocomplete
Place suggestions as the user types, from the same city index.
Matching places for a partial name, for populating a birth-place picker as the user types. Each result carries the place, country, state, a display name, coordinates, UTC offset and elevation.
Rate limit
None (not rate limited)
Authentication
None. Open endpoint, no key required.
Response keys
query, count, results
Query parameters for /location/autocomplete
Parameter
Type
Required
Default
Notes
query
string
No
null
Partial place name, at least 2 characters. Send query or q; with neither, or under 2 characters, the response is 400.
q
string
No
null
Same as query. If both are sent, query is used.
limit
integer
No
10
Maximum results. Values above 50 are treated as 50.
Example response (abridged; comments mark the cuts)
{
"status": "healthy"
/* …and a service name */
}
What POST /horoscope actually returns
The response is { "birth_details": {...}, "horoscope": {...}, "engine_revision": ... }. The example above shows a truncated excerpt because the real payload is several megabytes of JSON — printing it would be useless to a human and worse than useless to a model. Instead, here are all 33 keys always present inside horoscope, in the order the response lists them.
calendar_info
Panchanga and calendar context for the birth moment
bhava_chart
House (bhava) placements under the selected bhava_madhya_method, in 12 slots arranged by sign: slot 0 = Aries … slot 11 = Pisces. House 1 is the slot of the lagna's sign (the one holding the string “Ascendantℒ”), house n is slot (lagna slot + n − 1) mod 12, and each slot lists the bodies in that house. A body's slot can differ from its own sign; read its sign from divisional_charts (D-1).
ayanamsa_value
The ayanamsa in degrees actually applied
julian_day
Julian day number of the birth moment
divisional_charts
23 vargas, D-1 to D-144, each body with sign and longitude
nakshatra_pada
Nakshatra, pada, lord and degrees-in-nakshatra per body
amsa_rulers
D-150 Nadiamsa amsa rulers across planets, lagnas and sphutas
yogas
Classical yoga screening, with a summary of how many were found
doshas
Manglik, Kala Sarpa and the other classical doshas
chara_karakas
The eight variable karakas (Atma, Amatya, …)
sahams
The 36 sahams (Arabic parts)
upagrahas
The 11 shadowy sub-planets
special_lagnas
Bhava, Hora, Ghati and the other special ascendants
house_varnadas
Varnada lagna per house, V1 to V12
graha_arudhas
Arudha padas computed from the grahas
surya_arudhas
Arudhas measured from the Sun
chandra_arudhas
Arudhas measured from the Moon
house_relationships
Argala and virodhargala between houses
planetary_states
Retrograde, combust, exalted, debilitated and related lists
shad_bala
The six-fold planetary strength
shad_bala_required
The minimum Shad Bala each planet, Sun to Saturn, needs
bhava_bala
House strength
other_bala
Harsha, pancha and dwadhasa vargeeya bala, plus ishta and kashta phala
vimsopaka_bala
Twenty-point varga strength
vaiseshikamsa_bala
Vaiseshikamsa strength
shashtiamsa_rulers
The D-60 shashtiamsa and its classical nature for the lagna and each planet
ashtakavarga
BAV, SAV, SoAV and prastara grids, with the pindas
arudha_padhas
Arudha padas for every divisional chart (note the spelling, with an h)
sphuta
The 14 sphutas
graha_dashas
Graha dasha systems, Vimshottari included
rasi_dashas
Rasi dasha systems, Chara and Narayana included
saturn_transits
Sade Sati plus 4th/8th-house Saturn transits from Moon and Lagna
longevity_prediction
Classical longevity reference computations with the combinations behind them
Two more keys appear only when they apply:
surya_siddhanta
The Surya Siddhanta chart, present when calculation_type is "ss"
request_notes
Present when a setting could not be applied as sent, saying what was used instead
Two of these carry most of the weight. divisional_charts holds all 23 vargas keyed as D-1_rasi through D-144_dwadas_dwadasamsa, each mapping every body to a sign and a longitude. graha_dashas and rasi_dashas hold the timing systems. If you only need one of these, the MCP server has a tool per section and will not make you download the rest.
Note the spelling of arudha_padhas, with an h: the API returns the key exactly that way.
Errors
Errors come back as JSON. Most carry a detail field: a list of problems for a validation 422, a string otherwise. A 429 is the exception, with an error field instead. The message names the field and the constraint it broke, so it is worth surfacing to your users rather than swallowing.
400 Bad Request
Input the endpoint could not use. A well-formed request the calculation cannot serve: a date range that is too long or ends before it starts, an unknown planet name, a /location/search or /location/autocomplete query under 2 characters, or a /surya-siddhanta latitude beyond 66° north or south. detail is a string, often starting "Invalid input:".
404 Not Found
No location matched. GET /location/search found no place for the query. The message suggests adding a country name or code.
422 Unprocessable Entity
Validation failed. A required field is missing, has the wrong type, is out of range or is not one of the allowed values. detail is a list with one entry per problem, each carrying type, loc (where the field is), msg, input and ctx. Two further 422s carry a plain-string detail: a birth place inside the polar circles (beyond about 66.5° north or south), and a date on which the Sun does not rise or set at the place.
429 Too Many Requests
Rate limited. The endpoint's per-minute limit was exceeded for your IP address. The body is {"error": "Rate limit exceeded: 30 per 1 minute"}: an error field, not detail.
500 Internal Server Error
Calculation failed. An unexpected error while computing the result.
An input the endpoint could not use (/location/search?query=a)
HTTP/1.1 400 Bad Request
{"detail": "Query must be at least 2 characters"}
Before you build on this
There is no versioned URL prefix and no deprecation policy today. The shapes documented here are the shapes the API returns, but a breaking change would not announce itself with a new path. engine_revision tells you when calculated values change.
There is no uptime SLA, no support contract and no status page.
The API returns classical computation, not advice. Labels such as a match's rating band or a window marked auspicious are the classical classification of the computed values; how much weight to give them is your judgement, or your model's.
