JyotishToday API Reference

The JyotishToday API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

All API requests should be prefixed with the following base URL:

https://api.jyotish.today/v1

Base Request Format

// All requests must be sent securely via HTTPS.
// Unencrypted HTTP requests will be rejected.

curl -X POST https://api.jyotish.today/v1/[endpoint] \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Authentication

Authenticate your account by including your secret API key in the request headers. You can manage your API keys in the Developer Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub or client-side code.

Use the Authorization header with a Bearer token:

Authorization: Bearer jt_live_your_secret_key

Authentication Error Response

{
  "status": "error",
  "code": 401,
  "message": "Invalid or missing API key."
}

Birth Chart (Kundli)

POST /horoscope

Retrieves complete planetary positions, ascendant calculations, and Nakshatra details. Supports various Ayanamsa systems.

Request Parameters

Parameter	Description
day Integer Required	Birth day (1-31).
month Integer Required	Birth month (1-12).
year Integer Required	Birth year (e.g., 1986).
hour Integer Required	Birth hour in 24h format (0-23).
min Integer Required	Birth minute (0-59).
lat Float Required	Latitude in decimal format. Example: `28.6139`
lon Float Required	Longitude in decimal format. Example: `77.2090`
tzone Float Required	Timezone offset from UTC. Example: `5.5` for IST.
ayanamsa String	Defaults to `"Lahiri"`. Options: Raman, KP.

Response

{
  "status": "success",
  "metadata": {
    "ayanamsa_system": "Lahiri",
    "ayanamsa_value": "23.6720072"
  },
  "data": {
    "planet_positions": {
      "as": {
        "name": "Ascendant",
        "norm_degree": "20.6318908",
        "is_retro": false,
        "sign": {
          "number": 4,
          "name": "Cancer"
        },
        "nakshatra": {
          "name": "Ashlesha",
          "pada": 2,
          "lord": "Mercury"
        }
      },
      "su": {
        "name": "Sun",
        "norm_degree": "14.6968284",
        "is_retro": false,
        "sign": {
          "number": 6,
          "name": "Virgo"
        }
      }
      // ... mo, ma, me, ju, ve, sa, ra, ke
    }
  }
}

KP System

POST /kp-system

Calculates exact Krishnamurti Paddhati (KP) Placidus cusps, star lords, sub lords, and exact Nadi significators (e.g., houses 1, 3, 5, 8).

Accepts the exact same location and time parameters as the Horoscope endpoint. Additionally, you can pass a horary_number (1-249).

Response Snapshot

{
  "kp_system": {
    "cusps": {
      "1": {
        "degree": "110.631891",
        "sign_name": "Cancer",
        "sign_lord": "Moon",
        "star_lord": "Mercury",
        "sub_lord": "Venus"
      }
    },
    "planets": {
      "me": {
        "name": "Mercury",
        "star_lord": "Mars",
        "sub_lord": "Venus",
        "significators": [
          3,
          12
        ]
      }
    }
  }
}

Dashas (Vimshottari)

POST /dashas

Returns a deeply nested JSON object of Mahadashas and Antardashas based on the natal moon's exact longitude. Includes precise UTC timestamps for frontend timeline plotting.

Response

{
  "dashas": {
    "vimshottari": [
      {
        "planet": "Venus",
        "code": "ve",
        "start": "02-10-1986 02:10:00",
        "end": "09-03-1996 13:25:29",
        "timestamp_start": 195219089,
        "timestamp_end": 826358129,
        "sub_dasha": [
          {
            "planet": "Jupiter",
            "code": "ju",
            "start": "02-10-1986 02:10:00",
            "end": "07-01-1989 23:42:53",
            "timestamp_start": 516048101,
            "timestamp_end": 600199973
          }
        ]
      }
    ]
  }
}

Ashtakvarga

POST /ashtakvarga

Fetches complete Sarvashtakvarga and Bhinna Ashtakvarga points. Complex calculations like Trikon Shodhana and Ekadhipatya Shodhana are computed natively.

Response Snapshot

{
  "ashtakvarga": {
    "sarvashtakvarga": {
      "total_bindus_by_sign": {
        "1": 30,
        "2": 31,
        "3": 24,
        "4": 23,
        "10": 32,
        "total": 335
      }
    }
  }
}

Panchang & Muhurat

POST /panchang

Crucial for daily astrology apps. Retrieves the 5 limbs of time: Tithi, Vaara, Nakshatra, Yoga, and Karana, including exact percentage passed. Also returns Rahu Kaal and Yamaganda timings.

Response

{
  "panchang": {
    "tithi": {
      "name": "Trayodashi",
      "paksha": "Krishna Paksha",
      "percentage_passed": 97.33
    },
    "yoga": {
      "name": "Shubha",
      "percentage_passed": 88.05
    }
  },
  "muhurat": {
    "rahu_kaal": {
      "start": "13:59:53",
      "end": "15:32:22"
    }
  }
}