Skip to content
Occult API
POST/api/astro/tithi_scan/1 credit

Tithi year scan

A tithi is one thirtieth of the lunar month — the stretch of time during which the Moon gains a further 12 degrees of elongation on the Sun. Tithis are the unit almost every Hindu observance is defined on, and they do not line up with civil days: one can be as short as about nineteen hours or as long as about twenty-six, so a single occurrence often spans two dates. This endpoint takes one named tithi and returns every occurrence of it in a calendar year, with the true instant it begins and ends. `tithi_number` runs 1 to 30: 1-15 are Shukla Pratipada through Purnima, 16-29 are Krishna Pratipada through Chaturdashi, and 30 is Amavasya. `year` is the local calendar year and `timezone_as_float` decides which local year that is (5.5 for IST). No coordinates are required, because a tithi begins and ends at the same instant everywhere on Earth. The response is `{year, tithi_number, rows}`, with `rows` a chronological list of `{start, end}` UTC ISO timestamps — usually twelve or thirteen entries, since a given tithi recurs once per lunar month. Windows are not split at intervening sunrises, so an occurrence that runs across two civil days is returned as a single row.

https://yogataraapi.prahlad.app/api/astro/tithi_scan/
Test Request

Authentication

Send your key in the X-API-Key header. Keys are server-side credentials — never put one in browser JavaScript or a mobile app.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Request fields

FieldTypeRequiredNotes
timezone_as_floatnumber (double)required

UTC offset of the place, in hours, as a decimal. Example: 5.5 for India (UTC+05:30), -5 for New York in winter, 5.75 for Nepal. This is NOT validated against date_time - if the two disagree you get a successful response for the wrong moment, so derive both from the same source. Use the offset in force on that date, not today's: a summer birth in a country with daylight saving needs the summer offset.

tithi_numberintegerrequired

min 1 · max 30

yearintegerrequired

Year of birth as a number, e.g. 1990. Four digits.

min 1800 · max 2400

Example request

curl -X POST https://yogataraapi.prahlad.app/api/astro/tithi_scan/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timezone_as_float":5.5,"tithi_number":1,"year":2026}'

Response

{
  "data": {
    "year": 2026,
    "tithi_number": 1,
    "rows": [
      {
        "start": "2026-01-18T19:52:39+00:00",
        "end": "2026-01-19T20:45:19+00:00"
      },
      {
        "start": "2026-02-17T12:01:47+00:00",
        "end": "2026-02-18T11:28:41+00:00"
      },
      {
        "start": "2026-03-19T01:24:05+00:00",
        "end": "2026-03-19T23:23:24+00:00"
      },
      {
        "start": "2026-04-17T11:52:21+00:00",
        "end": "2026-04-18T08:41:36+00:00"
      },
      {
        "start": "2026-05-16T20:01:32+00:00",
        "end": "2026-05-17T16:11:46+00:00"
      },
      {
        "start": "2026-06-15T02:54:39+00:00",
        "end": "2026-06-15T23:01:51+00:00"
      },
      {
        "start": "2026-07-14T09:44:04+00:00",
        "end": "2026-07-15T06:21:58+00:00"
      },
      {
        "start": "2026-08-12T17:37:11+00:00",
        "end": "2026-08-13T15:12:30+00:00"
      },
      {
        "start": "2026-09-11T03:27:28+00:00",
        "end": "2026-09-12T02:17:22+00:00"
      },
      {
        "start": "2026-10-10T15:50:36+00:00",
        "end": "2026-10-11T16:02:05+00:00"
      },
      {
        "start": "2026-11-09T07:02:42+00:00",
        "end": "2026-11-10T08:31:14+00:00"
      },
      {
        "start": "2026-12-09T00:52:31+00:00",
        "end": "2026-12-10T03:17:14+00:00"
      }
    ]
  },
  "message": "successful",
  "is_error": false
}

Captured from a real call using the exact request above. Results sit under data.

Errors

Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.