Back to Docs

Panchang

Panchang

POST/api/v2/vedic/panchang

Calculate the V2 sunrise-based daily Panchang for a date, time, and location, including Tithi, Nakshatra, Yoga, Karana, and Rahu Kalam.

Authentication: send x-api-key.

Full URL

https://api.freeastroapi.com/api/v2/vedic/panchang
Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

What It Returns

A daily almanac payload with sunrise, sunset, weekday, lunar month, core Panchang elements, transition times, Rahu Kalam, request-time Panchang values, and calculation metadata.

Lunar months and year conventions (V2)

Lunar months use the Amanta calendar and are evaluated at local sunrise. The month remains the same throughout its lunation. Zero solar ingresses identify an Adhika month; two identify a Kshaya event. The response keeps the base month name separate from month_type so clients can distinguish identity from classification.

  • chaitra_shukladi (default): advance the year at the opening new moon of the first Chaitra lunation, including Adhika Chaitra.
  • chaitra_krishnadi: advance at the full moon preceding that Chaitra lunation. This supports a Purnimanta-style year boundary; month output stays Amanta.
  • kartika_shukladi: advance at the opening new moon of the first Kartika lunation, including Adhika Kartika, for the Gujarati year convention.

These are calendar phase rules, not festival-observance dates. For example, Delhi sunrise on March 19, 2026 precedes the Chaitra conjunction, so the default daily year changes on March 20. Changing the request hour or adding "lang": "hi"does not change those sunrise facts. Language does not select a region or calendar.

Kshaya example: January 20, 1983

The continuing month is Pausha; Magha is omitted as a separate lunation. Some calendars label this period “Kshaya Magha”. Read both identities:

{
  "lunar_month": {
    "number": 10,
    "name": "Pausha",
    "amanta": true,
    "month_type": "kshaya",
    "omitted_month": {
      "number": 11,
      "name": "Magha"
    },
    "vikram_samvat": 2039,
    "vikram_samvat_convention": "chaitra_shukladi"
  }
}

In Hindi, these names become पौष and माघ. The identifiers andmonth_type stay unchanged. If a year-start month is omitted, its containing Kshaya lunation supplies the year boundary.

This corrects earlier approximate month names and the fixed March 22 year cutoff. The shared V2 Panchang calculation, including the default English result embedded in /calculate, uses these corrections. The standalone endpoint acceptsyear_convention; V1 is unchanged. The /calculate response omits omitted_month when it is null.

Dates without sunrise or sunset

V2 returns HTTP 422 when there is no sunrise on the requested local date, or no sunset within the following 24 hours. This can happen during polar day or night. A later date's sunrise is never substituted. The same error applies when /api/v2/vedic/calculate includes Panchang.

Read detail.code for sunrise_unavailable orsunset_unavailable. The error includes detail.dateand an English detail.message, including for Hindi requests.

Example Request

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/panchang" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "year": 1997,
  "month": 9,
  "day": 22,
  "hour": 23,
  "minute": 25,
  "city": "Mumbai",
  "lat": 19.391928,
  "lng": 72.839732,
  "tz_str": "Asia/Kolkata",
  "ayanamsha": "lahiri",
  "house_system": "whole_sign",
  "node_type": "mean"
}'

Request Parameters

Provide either city or both lat and lng. Coordinates are recommended for stable production results.

Field
year
Type
integer
Required
Yes
Description
Birth year.
Field
month
Type
integer
Required
Yes
Description
Birth month (1-12).
Field
day
Type
integer
Required
Yes
Description
Birth day.
Field
hour
Type
integer
Required
Yes
Description
Birth hour (0-23).
Field
minute
Type
integer
Required
Yes
Description
Birth minute (0-59).
Field
city
Type
string
Required
No
Description
Birth city. Optional when lat/lng are provided.
Field
lat
Type
float
Required
No
Description
Birth latitude. Recommended for production.
Field
lng
Type
float
Required
No
Description
Birth longitude. Recommended for production.
Field
tz_str
Type
string
Required
No
Description
Optional timezone override such as Asia/Kolkata, Europe/London, AUTO, or LMT. Defaults to AUTO when omitted.
Field
ayanamsha
Type
string
Required
No
Description
Vedic ayanamsha. Default is lahiri.
Field
house_system
Type
string
Required
No
Description
House system. Default is whole_sign.
Field
node_type
Type
string
Required
No
Description
Lunar node type: mean or true.
Field
lang
Type
string
Required
No
Description
V2 only. Supported languages: "en" (English, default) and "hi" (Hindi). "language" is also accepted as an alias. If both are supplied, they must match. Unsupported values or conflicting aliases return HTTP 422.
Field
year_convention
Type
string
Required
No
Description
V2 only. "chaitra_shukladi" (default), "chaitra_krishnadi", or "kartika_shukladi". Selects the Vikram Samvat year boundary at local sunrise. Does not change the Amanta lunar month or language. Unsupported values return HTTP 422.

Response Shape

Field
date
Type
string
Required
n/a
Description
Requested local date.
Field
sunrise / sunset
Type
string
Required
n/a
Description
Local sunrise and sunset times.
Field
weekday
Type
object
Required
n/a
Description
Weekday number and name.
Field
lunar_month
Type
object
Required
n/a
Description
Lunar month name, Amanta flag, and Vikram Samvat year.
Field
tithi / nakshatra / yoga / karanas
Type
object
Required
n/a
Description
Core Panchang elements with transition times.
Field
rahu_kalam
Type
object
Required
n/a
Description
Daily Rahu Kalam start and end.
Field
request_time_panchang
Type
object
Required
n/a
Description
Panchang values active at the requested local time.
Field
metadata
Type
object
Required
n/a
Description
Endpoint version, ruleset, ayanamsha, timezone, and calculation basis.
Field
lunar_month.number
Type
integer
Required
n/a
Description
Stable month identity: Chaitra = 1 through Phalguna = 12.
Field
lunar_month.month_type
Type
string
Required
n/a
Description
"regular", "adhika" (intercalary), or "kshaya" (a lunation containing an omitted month). These machine values remain unchanged in Hindi.
Field
lunar_month.omitted_month
Type
object | null
Required
n/a
Description
For Kshaya, the number and localized name of the month omitted as a separate lunation. The outer number/name identify the continuing month. Null otherwise.
Field
lunar_month.vikram_samvat_convention
Type
string
Required
n/a
Description
The year convention used for vikram_samvat. Independent of lang.
Field
metadata.calendar_ruleset_version
Type
string
Required
n/a
Description
"amanta_conjunction_v1": lunar months derived from exact conjunctions and solar ingresses.

Real Request Example

This request was captured from the live production endpoint and is the same payload used in the code tabs.

{
  "year": 1997,
  "month": 9,
  "day": 22,
  "hour": 23,
  "minute": 25,
  "city": "Mumbai",
  "lat": 19.391928,
  "lng": 72.839732,
  "tz_str": "Asia/Kolkata",
  "ayanamsha": "lahiri",
  "house_system": "whole_sign",
  "node_type": "mean"
}

Response Example

V2

Generated from the current V2 implementation for the example request, including explicit lunar-month classification and year convention.

{
  "date": "1997-09-22",
  "location": {
    "lat": 19.391928,
    "lng": 72.839732
  },
  "sunrise": "06:27:14",
  "sunset": "18:35:15",
  "weekday": {
    "number": 2,
    "name": "Monday"
  },
  "lunar_month": {
    "number": 6,
    "name": "Bhadrapada",
    "month_type": "regular",
    "omitted_month": null,
    "amanta": true,
    "vikram_samvat": 2054,
    "vikram_samvat_convention": "chaitra_shukladi"
  },
  "tithi": {
    "number": 21,
    "name": "Shashti",
    "paksha": "Krishna",
    "ends_at": "07:38:58",
    "ends_at_iso": "1997-09-22T07:38:58.096672+05:30"
  },
  "nakshatra": {
    "number": 4,
    "name": "Rohini",
    "pada": 2,
    "lord": "Moon",
    "ends_at": "18:29:18",
    "ends_at_iso": "1997-09-22T18:29:18.330247+05:30"
  },
  "yoga": {
    "number": 16,
    "name": "Siddhi",
    "ends_at": "25:42:19",
    "ends_at_iso": "1997-09-23T01:42:19.175767+05:30"
  },
  "karanas": [
    {
      "number": 6,
      "name": "Vanij",
      "ends_at": "07:38:58",
      "ends_at_iso": "1997-09-22T07:38:58.096672+05:30"
    },
    {
      "number": 7,
      "name": "Vishti",
      "ends_at": "19:15:41",
      "ends_at_iso": "1997-09-22T19:15:41.241485+05:30"
    },
    {
      "number": 1,
      "name": "Bhav",
      "ends_at": "31:04:25",
      "ends_at_iso": "1997-09-23T07:04:25.830624+05:30"
    }
  ],
  "rahu_kalam": {
    "start": "07:58",
    "end": "09:29"
  },
  "request_time_panchang": {
    "tithi": {
      "number": 22,
      "name": "Saptami",
      "paksha": "Krishna"
    },
    "nakshatra": {
      "number": 5,
      "name": "Mrigashirsha",
      "pada": 1,
      "lord": "Mars"
    },
    "yoga": {
      "number": 16,
      "name": "Siddhi"
    },
    "karana": {
      "number": 1,
      "name": "Bhav"
    },
    "sun_sign": {
      "sign_id": 6,
      "name": "Virgo",
      "degree": 5.9305
    },
    "moon_sign": {
      "sign_id": 2,
      "name": "Taurus",
      "degree": 26.0527
    }
  },
  "metadata": {
    "endpoint_version": "v2",
    "ruleset_version": "astrosage_panchang_v1",
    "calendar_ruleset_version": "amanta_conjunction_v1",
    "ayanamsha": "lahiri",
    "timezone_used": "Asia/Kolkata",
    "calculation_basis": "sunrise_day_with_transition_times",
    "request_local_time": "1997-09-22T23:25:00+05:30"
  }
}

Related Docs

Full Vedic calculateBasic Vedic chart

FAQ

Is Panchang available in Hindi?

Yes. Send "lang": "hi" to /api/v2/vedic/panchang for Hindi names, including request-time Panchang labels. "language": "hi" is also accepted. Omit the parameter or use "en" for English. JSON keys, identifiers and calculated values stay the same. This option applies to the standalone V2 endpoint; Panchang inside /calculate remains in English.