{ "openapi": "3.1.0", "info": { "title": "Vedic Astrology Calculation API", "version": "1.0.0", "description": "Open REST API for Vedic astrology calculations: birth charts, divisional charts, dashas, yogas, doshas, transits, panchang, muhurta and marriage matching. No API key. Send birth details in the JSON body, never in the URL. Usage terms and data handling are published on the /api-mcp page of the site this file came from." }, "servers": [ { "url": "https://jagannatha-hora-359167915530.europe-west1.run.app" } ], "tags": [ { "name": "Birth charts & matching" }, { "name": "Transits" }, { "name": "Panchang & muhurta" }, { "name": "Places" }, { "name": "Service" } ], "paths": { "/horoscope": { "post": { "operationId": "horoscope", "summary": "Full birth chart", "description": "Every calculation for one birth moment in a single response: 23 divisional charts, nakshatras and padas, yogas, doshas, chara karakas, sahams, upagrahas, special lagnas, sphutas, arudhas, planetary states, Shad Bala and the other strengths, Ashtakavarga, graha and rasi dashas, Saturn transits and longevity. The response is large (several megabytes of JSON, sent compressed), so cache it.\n\nThe same inputs return the same chart until `engine_revision` changes, so cache by input and `engine_revision`.\n\nWith `calculation_type` `ss` the chart also carries a `surya_siddhanta` section. When a setting cannot be applied (for example a `chart_method` a chart does not have), the chart carries `request_notes` saying so.\n\nRate limit: 30 requests a minute per IP.", "tags": [ "Birth charts & matching" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "birth_details": { "type": "object", "description": "The inputs as used, including the UTC offset applied and where it came from. Keys: date, time, place, latitude, longitude, timezone, timezone_used, timezone_derived, timezone_source, request_settings." }, "horoscope": { "type": "object", "description": "The chart, one key per section. Keys: calendar_info, bhava_chart, ayanamsa_value, julian_day, divisional_charts, nakshatra_pada, amsa_rulers, yogas, doshas, chara_karakas, sahams, upagrahas, special_lagnas, house_varnadas, graha_arudhas, surya_arudhas, chandra_arudhas, house_relationships, planetary_states, shad_bala, shad_bala_required, bhava_bala, other_bala, vimsopaka_bala, vaiseshikamsa_bala, shashtiamsa_rulers, ashtakavarga, arudha_padhas, sphuta, graha_dashas, rasi_dashas, saturn_transits, longevity_prediction." }, "engine_revision": { "description": "An integer that goes up whenever calculation results change. Store it with cached charts and recompute when it changes." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "place": { "type": "string", "description": "Birth place name, echoed in the response. Coordinates decide the calculation." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours at birth, -12 to 14 (5.5 for India). By default the API works out the historically correct offset, including daylight saving, from the coordinates and date; see timezone_mode." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level." }, "gender": { "type": "string", "enum": [ "male", "female" ], "description": "Optional. A few classical yogas depend on gender; when it is omitted, those yogas are left out rather than guessed." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL", "SIDM_USER" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." }, "ayanamsa_value": { "type": "number", "description": "Your own ayanamsa in degrees, -30 to 30. Used with ayanamsa_mode SIDM_USER." }, "calculation_type": { "type": "string", "enum": [ "drik", "ss" ], "default": "drik", "description": "drik for modern (drik) positions, ss for Surya Siddhanta." }, "node_type": { "type": "string", "enum": [ "mean", "true" ], "default": "mean", "description": "Rahu and Ketu as the mean or the true lunar node." }, "bhava_madhya_method": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ], "default": 1, "description": "House system for the bhava chart: 1 equal houses with the lagna at the middle, 2 equal houses with the lagna at the start, 3 Sripati, 4 KP (Placidus cusps), 5 whole sign." }, "timezone_mode": { "type": "string", "enum": [ "auto", "file" ], "default": "auto", "description": "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. The response reports the offset used." }, "language": { "type": "string", "enum": [ "en", "hi", "ka", "ta", "te" ], "default": "en", "description": "Language for names in the response: English, Hindi, Kannada, Tamil or Telugu." }, "pravesha_type": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "description": "0 natal chart, 1 annual (varsha pravesha), 2 tithi pravesha." }, "years": { "type": "integer", "default": 1, "description": "Year number for annual charts, 1 to 120." }, "months": { "type": "integer", "default": 1, "description": "Month number for monthly charts, 1 to 12." }, "sixty_hours": { "type": "integer", "default": 1, "description": "Sixty-hour period number for hora progressions, 1 to 1000." }, "divisional_chart_factor": { "type": "integer", "default": 1, "description": "The divisional chart that chart_method applies to (1 = D-1, 9 = D-9, and so on)." }, "chart_method": { "type": "integer", "default": 1, "description": "Construction method for that divisional chart, 1 to 6; how many exist depends on the chart. An unavailable method falls back to 1 and is reported in the response." }, "base_rasi": { "type": "integer", "description": "For custom divisional charts, which this endpoint does not return. 0 to 11." }, "count_from_end_of_sign": { "type": "boolean", "description": "For custom divisional charts, which this endpoint does not return." }, "varnada_method": { "type": "integer", "default": 1, "description": "Method for the varnada outputs (house varnadas and the varnada dasha), 1 to 4. Higher values fall back to 1 and are reported in the response." }, "tamil_month_method": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "default": 3, "description": "How the Tamil month is reckoned, 0 to 3: 0 an alternative traditional rule, 1 starts at sunset, 2 at 10 AM, 3 at midday UTC." }, "kali_start_year": { "type": "integer", "enum": [ 1, 13 ], "default": 13, "description": "Sixty-year cycle naming: 1 starts at Prabhava (South Indian), 13 at Pramaadhi (North Indian)." } }, "required": [ "date", "time", "place", "latitude", "longitude", "timezone" ] }, "example": { "date": "1990-01-01", "time": "06:30:00", "place": "Bengaluru", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 } } } } } }, "/marriage-match": { "post": { "operationId": "marriage-match", "summary": "Marriage compatibility", "description": "Ashtakoota (Guna Milan) and the additional poruthams for North Indian matching, the ten poruthams for South Indian matching, each person's nakshatra and rasi, their dosha scores, and the Beeja and Kshetra rasi.\n\nRate limit: 30 requests a minute per IP.", "tags": [ "Birth charts & matching" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "boy": { "type": "object", "description": "Each person's nakshatra, pada and rasi. Keys: nakshatra_number, nakshatra_name, pada_number, raasi_number, raasi_name." }, "girl": { "type": "object", "description": "Each person's nakshatra, pada and rasi. Keys: nakshatra_number, nakshatra_name, pada_number, raasi_number, raasi_name." }, "north_indian": { "type": "object", "description": "Ashtakoota matching. Keys: match_system, eight_koota_porutham, four_additional_porutham, overall_compatibility." }, "south_indian": { "type": "object", "description": "Ten-porutham matching. Keys: match_system, ten_porutham, overall_compatibility." }, "boy_dosha_data": { "type": "object", "description": "Dosha scores for each person. Keys: mars_dosha, sun_dosha, saturn_dosha, rahu_ketu_dosha, total_dosha." }, "girl_dosha_data": { "type": "object", "description": "Dosha scores for each person. Keys: mars_dosha, sun_dosha, saturn_dosha, rahu_ketu_dosha, total_dosha." }, "beeja_rasi": { "description": "Beeja and Kshetra rasi of the pair." }, "kshetra_rasi": { "description": "Beeja and Kshetra rasi of the pair." }, "engine_revision": { "description": "Goes up whenever calculation results change." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "boy_birth_details": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14. The API works out the historically correct offset for the place and date from the coordinates, and uses this value only where no time zone is known there." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level." } }, "required": [ "date", "time", "latitude", "longitude", "timezone" ], "description": "The boy's birth details." }, "girl_birth_details": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14. The API works out the historically correct offset for the place and date from the coordinates, and uses this value only where no time zone is known there." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level." } }, "required": [ "date", "time", "latitude", "longitude", "timezone" ], "description": "The girl's birth details." } }, "required": [ "boy_birth_details", "girl_birth_details" ] }, "example": { "boy_birth_details": { "date": "1990-01-01", "time": "06:30:00", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 }, "girl_birth_details": { "date": "1992-03-15", "time": "14:20:00", "latitude": 13.0827, "longitude": 80.2707, "timezone": 5.5 } } } } } } }, "/saturn-timeline": { "post": { "operationId": "saturn-timeline", "summary": "Sade Sati and Saturn timeline", "description": "Sade Sati and dhaiyya periods for a birth chart, measured from the Moon sign. `sadeSati` describes the cycle in progress; if none is running, the next one (or the most recent, if none is ahead). `nextCycle` is the next cycle to begin.\n\nWhich cycle is current, and the months remaining, are measured from today's date, so the response changes over time for the same inputs.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Birth charts & matching" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "saturn_timeline": { "type": "object", "description": "The Moon sign and the Saturn periods measured from it. Keys: moonSign, moonDegree, sadeSati, dhaiyya, nextCycle." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14 (5.5 for India)." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "RAMAN" ], "default": "LAHIRI", "description": "LAHIRI or RAMAN only on this endpoint." }, "detail": { "type": "string", "enum": [ "summary", "full" ], "default": "summary", "description": "summary returns the phases; full adds the month-by-month detail." } }, "required": [ "date", "time", "latitude", "longitude", "timezone" ] }, "example": { "date": "1990-01-01", "time": "06:30:00", "place": "Bengaluru", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 } } } } } }, "/surya-siddhanta": { "post": { "operationId": "surya-siddhanta", "summary": "Surya Siddhanta chart", "description": "A natal chart computed by the Surya Siddhanta method: the lagna, planetary positions and panchanga, with the ayanamsa it implies compared against the mode you choose.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Birth charts & matching" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "birth_details": { "type": "object", "description": "The inputs as used, including the UTC offset applied. Keys: date, time, place, latitude, longitude, elevation, timezone, timezone_used, timezone_derived, timezone_source." }, "surya_siddhanta": { "type": "object", "description": "The chart. Keys: method, epoch, ayanamsa, lagna, planets, panchanga." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond 66° north or south are rejected with 400." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours at birth, -12 to 14 (5.5 for India). By default the API works out the historically correct offset, including daylight saving, from the coordinates and date; see timezone_mode." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level. Echoed only." }, "timezone_mode": { "type": "string", "enum": [ "auto", "file" ], "default": "auto", "description": "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. The response reports the offset used." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL", "SIDM_USER" ], "default": "LAHIRI", "description": "The ayanamsa to compare the Surya Siddhanta result against." }, "ayanamsa_value": { "type": "number", "description": "Your own ayanamsa in degrees, -30 to 30. Used with ayanamsa_mode SIDM_USER." } }, "required": [ "date", "time", "latitude", "longitude", "timezone" ] }, "example": { "date": "1990-01-01", "time": "06:30:00", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 } } } } } }, "/gochara": { "post": { "operationId": "gochara", "summary": "Transits against a birth chart", "description": "Where the planets are at a target date and time, read against a birth chart: each planet's sign, house from the lagna and Moon, nakshatra, Ashtakavarga support and the panchanga and muhurta windows of the day.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Transits" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "birth_details": { "type": "object", "description": "The birth inputs as used. Keys: date, time, place, latitude, longitude, timezone." }, "gochara": { "type": "object", "description": "The transit snapshot. Keys: target, natal_ref, panchanga, muhurta, planets, person_strength, transit_charts." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours at birth, -12 to 14 (5.5 for India). By default the API works out the historically correct offset, including daylight saving, from the coordinates and date; see timezone_mode." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." }, "node_type": { "type": "string", "enum": [ "mean", "true" ], "default": "mean", "description": "Rahu and Ketu as the mean or the true lunar node." }, "timezone_mode": { "type": "string", "enum": [ "auto", "file" ], "default": "auto", "description": "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. The response reports the offset used." }, "target_date": { "type": "string", "description": "The date to read transits for, YYYY-MM-DD." }, "target_time": { "type": "string", "default": "12:00:00", "description": "Time on the target date, HH:MM:SS. Defaults to local noon." }, "event_place": { "type": "string", "description": "Name of the place the transit is read for. Defaults to the birth place." }, "event_latitude": { "type": "number", "description": "Latitude of the event place. Defaults to the birth latitude." }, "event_longitude": { "type": "number", "description": "Longitude of the event place. Defaults to the birth longitude." }, "event_timezone": { "type": "number", "description": "UTC offset of the event place, in hours. The API works out the offset from the event coordinates where it can; this value, or the birth offset, is the fallback." }, "event_elevation": { "type": "number", "description": "Elevation of the event place, in metres." }, "include": { "type": "array", "items": { "type": "string" }, "description": "Optional sections: \"ashtakavarga\", \"gochara_phala\", \"transit_charts\". All three are included by default; pass [] for none, or a subset." } }, "required": [ "date", "time", "latitude", "longitude", "timezone", "target_date" ] }, "example": { "date": "1990-01-01", "time": "06:30:00", "place": "Bengaluru", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5, "target_date": "2026-10-03" } } } } } }, "/gochara/range": { "post": { "operationId": "gochara-range", "summary": "Transits day by day", "description": "The same transit reading as /gochara, once per day across a date range of up to 60 days.\n\nRate limit: 30 requests a minute per IP.", "tags": [ "Transits" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "gochara_range": { "type": "object", "description": "One entry per day. Keys: range, place, ayanamsa_mode, natal_ref, count, days." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14. The API works out the historically correct offset for the place and date from the coordinates, and uses this value only where no time zone is known there." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." }, "from_date": { "type": "string", "description": "First day, YYYY-MM-DD." }, "to_date": { "type": "string", "description": "Last day, YYYY-MM-DD. The range covers at most 60 days, counting both ends (400 otherwise)." }, "time_of_day": { "type": "string", "default": "12:00:00", "description": "Time used on each day, HH:MM:SS. Defaults to local noon." }, "event_place": { "type": "string", "description": "Name of the place the transit is read for. Defaults to the birth place." }, "event_latitude": { "type": "number", "description": "Latitude of the event place. Defaults to the birth latitude." }, "event_longitude": { "type": "number", "description": "Longitude of the event place. Defaults to the birth longitude." }, "event_timezone": { "type": "number", "description": "UTC offset of the event place, in hours. The API works out the offset from the event coordinates where it can; this value, or the birth offset, is the fallback." }, "event_elevation": { "type": "number", "description": "Elevation of the event place, in metres." }, "include": { "type": "array", "items": { "type": "string" }, "description": "Optional sections per day: \"ashtakavarga\" and \"gochara_phala\". Both are included by default; pass [] for none, or one of them." } }, "required": [ "date", "time", "latitude", "longitude", "timezone", "from_date", "to_date" ] }, "example": { "date": "1990-01-01", "time": "06:30:00", "place": "Bengaluru", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5, "from_date": "2026-10-01", "to_date": "2026-10-07" } } } } } }, "/gochar": { "post": { "operationId": "gochar", "summary": "Today's planetary positions", "description": "Where the nine planets are on a date, for a place, with no birth chart: sign, nakshatra, retrograde state and the day's highlights.\n\nResponses can be cached for six hours.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Transits" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "gochar": { "type": "object", "description": "Positions for the date. Keys: date, place, planets, highlights." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "The date, YYYY-MM-DD." }, "latitude": { "type": "number", "description": "Decimal degrees, -90 to 90, north positive." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14. The API works out the historically correct offset for the place and date from the coordinates, and uses this value only where no time zone is known there." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." } }, "required": [ "date", "latitude", "longitude", "timezone" ] }, "example": { "date": "2026-10-03", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 } } } } } }, "/gochar/events": { "post": { "operationId": "gochar-events", "summary": "Upcoming transit events", "description": "Sign changes and other transit events for the chosen planets over a date range of up to 90 days, with no birth chart.\n\nResponses can be cached for six hours.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Transits" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "gochar_events": { "type": "object", "description": "Events in the range. Keys: range, timezone, ayanamsa_mode, planets, events." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string", "description": "Range start, YYYY-MM-DD." }, "to_date": { "type": "string", "description": "Range end, YYYY-MM-DD. At most 90 days after from_date." }, "latitude": { "type": "number", "description": "Decimal degrees, -90 to 90. Used for the display timezone." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset, in hours, for expressing event dates. The API works out the offset from the coordinates where it can; this value is the fallback." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "planets": { "type": "array", "items": { "type": "string" }, "description": "Planet names. Defaults to all nine: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." } }, "required": [ "from_date", "to_date", "latitude", "longitude", "timezone" ] }, "example": { "from_date": "2026-10-01", "to_date": "2026-10-31", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 } } } } } }, "/planet-ingress": { "post": { "operationId": "planet-ingress", "summary": "When a planet changes sign", "description": "The dates each chosen planet enters a new sign over a date range of up to about five years.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Transits" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "planet_ingress": { "type": "object", "description": "Sign changes in the range. Keys: range, timezone, ayanamsa_mode, planets, ingresses." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planets": { "type": "array", "items": { "type": "string" }, "description": "Planet names (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu). Defaults to Saturn, Jupiter, Rahu and Ketu. An unknown name returns 400." }, "from_date": { "type": "string", "description": "Range start, YYYY-MM-DD." }, "to_date": { "type": "string", "description": "Range end, YYYY-MM-DD. Must be after from_date and at most about five years later (400 otherwise)." }, "timezone": { "type": "number", "default": 0, "description": "UTC offset, in hours, that crossing dates are expressed in. Defaults to UTC." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." } }, "required": [ "from_date", "to_date" ] }, "example": { "from_date": "2026-10-01", "to_date": "2027-12-31", "timezone": 5.5 } } } } } }, "/panchang": { "post": { "operationId": "panchang", "summary": "Daily panchang", "description": "The panchang for a date and place: vaara, tithi, nakshatra, yoga and karana, sun and moon rise and set, auspicious and inauspicious windows, Choghadiya, the lunar month, ritu, ayana, samvat and the Sun and Moon signs.\n\nRahu Kalam is under `inauspicious.rahu_kalam` and Abhijit muhurta under `auspicious.abhijit_muhurta`.\n\nResponses can be cached for six hours.\n\nRate limit: 60 requests a minute per IP.", "tags": [ "Panchang & muhurta" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "panchang": { "type": "object", "description": "The day's panchang. Keys: date, place, sunrise, sunset, moonrise, moonset, day_length, vaara, paksha, tithi, nakshatra, yoga, karana, auspicious, inauspicious, choghadiya, month, ritu, ayana, samvat, signs." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "The date, YYYY-MM-DD." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond 66° north or south are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14. The API works out the historically correct offset for the place and date from the coordinates, and uses this value only where no time zone is known there." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." } }, "required": [ "date", "latitude", "longitude", "timezone" ] }, "example": { "date": "2026-10-03", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5 } } } } } }, "/muhurta": { "post": { "operationId": "muhurta", "summary": "Auspicious dates for an event", "description": "Scores each day in a range of up to 90 days for an event type, using the classical day factors and the person's own strength on that day, and returns the scored candidates with the windows to avoid.\n\nRate limit: 30 requests a minute per IP.", "tags": [ "Panchang & muhurta" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "muhurta": { "type": "object", "description": "Scored days for the event. Keys: event_type, event_label, range, rules_applied, weights, day_part_resolution_minutes, candidates." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." }, "429": { "description": "Rate limit exceeded." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "description": "Birth date, YYYY-MM-DD. Years 1800 to 2100." }, "time": { "type": "string", "description": "Birth time, HH:MM:SS on a 24-hour clock." }, "place": { "type": "string", "default": "", "description": "Place name, echoed in the response. Coordinates decide the calculation." }, "latitude": { "type": "number", "description": "Decimal degrees, north positive. Places beyond about 66.5° north or south (inside the polar circles) are rejected with 422." }, "longitude": { "type": "number", "description": "Decimal degrees, -180 to 180, east positive." }, "timezone": { "type": "number", "description": "UTC offset in hours, -12 to 14. The API works out the historically correct offset for the place and date from the coordinates, and uses this value only where no time zone is known there." }, "elevation": { "type": "number", "default": 0, "description": "Metres above sea level." }, "ayanamsa_mode": { "type": "string", "enum": [ "LAHIRI", "TRUE_CITRA", "TRUE_LAHIRI", "KP", "FAGAN", "RAMAN", "USHASHASHI", "YUKTESHWAR", "SURYASIDDHANTA", "SURYASIDDHANTA_MSUN", "ARYABHATA", "ARYABHATA_MSUN", "SS_CITRA", "TRUE_REVATI", "SS_REVATI", "TRUE_PUSHYA", "TRUE_MULA", "KP-SENTHIL", "SENTHIL" ], "default": "LAHIRI", "description": "Ayanamsa (sidereal zodiac) to use. Case-insensitive. Send one of the listed modes: on some endpoints an unrecognised value is not rejected and LAHIRI is used." }, "event_type": { "type": "string", "description": "The event. GET /muhurta/events lists the valid values." }, "from_date": { "type": "string", "description": "Range start, YYYY-MM-DD." }, "to_date": { "type": "string", "description": "Range end, YYYY-MM-DD. The range covers at most 90 days, counting both ends (400 otherwise)." }, "event_place": { "type": "string", "description": "Name of the place the transit is read for. Defaults to the birth place." }, "event_latitude": { "type": "number", "description": "Latitude of the event place. Defaults to the birth latitude." }, "event_longitude": { "type": "number", "description": "Longitude of the event place. Defaults to the birth longitude." }, "event_timezone": { "type": "number", "description": "UTC offset of the event place, in hours. The API works out the offset from the event coordinates where it can; this value, or the birth offset, is the fallback." }, "event_elevation": { "type": "number", "description": "Elevation of the event place, in metres." }, "day_part_resolution_minutes": { "type": "integer", "default": 15, "description": "5 to 60. Echoed in the response; it does not currently change the scoring." }, "respect_inauspicious_windows": { "type": "boolean", "default": true, "description": "Report the Rahu Kalam, Gulika and Yamaganda windows to avoid." } }, "required": [ "date", "time", "latitude", "longitude", "timezone", "event_type", "from_date", "to_date" ] }, "example": { "date": "1990-01-01", "time": "06:30:00", "place": "Bengaluru", "latitude": 12.9716, "longitude": 77.5946, "timezone": 5.5, "event_type": "griha_pravesha_own", "from_date": "2026-10-05", "to_date": "2026-10-20" } } } } } }, "/muhurta/events": { "get": { "operationId": "muhurta-events", "summary": "Event types for muhurta", "description": "The event types /muhurta accepts, each with a readable label.\n\nNo per-minute limit.", "tags": [ "Panchang & muhurta" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "object", "description": "One entry per event type: griha_pravesha_own, griha_pravesha_rented, travel_prayana, vehicle_purchase, business_shop_opening, property_purchase_registration. Keys: event_type, label, source." } } } } } } } } }, "/location/search": { "get": { "operationId": "location-search", "summary": "Coordinates for a place name", "description": "The best match for a place name from an index of more than 162,000 cities, with its coordinates and UTC offset. Use it to fill latitude, longitude and timezone before calling a chart endpoint.\n\nReturns 404 when nothing matches and 400 when the query is shorter than 2 characters.\n\nThe query is part of the URL, so it appears in request logs (see Your Data).\n\nNo per-minute limit.", "tags": [ "Places" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "place": { "description": "Matched place name." }, "latitude": { "description": "Coordinates in decimal degrees." }, "longitude": { "description": "Coordinates in decimal degrees." }, "timezone": { "description": "The place's standard UTC offset in hours (no daylight saving)." }, "country": { "description": "Where the place is (state when known), and a display label." }, "state": { "description": "Where the place is (state when known), and a display label." }, "displayName": { "description": "Where the place is (state when known), and a display label." }, "source": { "description": "Where the match came from." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "404": { "description": "No place matches the query." } }, "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Place name, at least 2 characters, e.g. \"Chennai, India\". Either query or q is required.", "schema": { "type": "string" }, "example": "Chennai, India" }, { "name": "q", "in": "query", "required": false, "description": "Same as query.", "schema": { "type": "string" } } ] } }, "/location/autocomplete": { "get": { "operationId": "location-autocomplete", "summary": "Place suggestions as you type", "description": "Up to 50 matching places for a partial name, for a search-as-you-type box.\n\nThe query is part of the URL, so it appears in request logs (see Your Data).\n\nNo per-minute limit.", "tags": [ "Places" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "description": "The text searched." }, "count": { "description": "How many results came back." }, "results": { "type": "object", "description": "Matching places. Each timezone is the place's standard UTC offset (no daylight saving). Keys: place, country, state, displayName, latitude, longitude, timezone, elevation." } } } } } }, "400": { "description": "The input cannot be used for this calculation. The detail says why." }, "422": { "description": "A field is missing or out of range. The detail says which." } }, "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Partial place name, at least 2 characters. Either query or q is required.", "schema": { "type": "string" }, "example": "Chenn" }, { "name": "q", "in": "query", "required": false, "description": "Same as query.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results, up to 50.", "schema": { "type": "integer", "default": 10 }, "example": 5 } ] } }, "/health": { "get": { "operationId": "health", "summary": "Health check", "description": "Returns 200 with a status field when the API is up. Use it for uptime checks.\n\nNo per-minute limit.", "tags": [ "Service" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "\"healthy\" when the API is up." }, "service": { "description": "Service name." } } } } } } } } } } }