Browse all documentation

Calendar systems API reference

Convert a date to other calendar systems, find the Gregorian date of a native date and read the official Hijri months of a country.

Request

The calendar systems API converts a date between the Gregorian calendar and thirteen other calendars: Chinese, Vietnamese, Korean, Japanese, Hijri, Persian, Hindu, Tamil, Malayalam, Bengali, Odia, Nepali and Indian national. It has three operations. Use your Narwhal bearer key.

OperationGET endpointMCP tool
Convert a date to other calendarsGET /v1/calendars/dates/{date}calendars_convert_dates
Find the Gregorian date of a date in another calendarGET /v1/calendars/dates/from/{calendar}calendars_find_dates
Read the official Hijri months of a country and yearGET /v1/calendars/hijri/{country}/{year}calendars_get_hijri_year
Convert 20 March 2026 to the Hijri and Chinese calendars, with the official Indonesian Hijri day
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/2026-03-20?calendars=hijri,chinese&country=IDN" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "date": "2026-03-20",
  "hijri": {
    "year": 1447,
    "month": 10,
    "day": 1,
    "days_in_month": 29,
    "after_sunset": false,
    "adjustment": 0,
    "method": "umm_al_qura",
    "official": {
      "country": "IDN",
      "day": 30,
      "status": "published"
    }
  },
  "chinese": {
    "year": 2026,
    "month": 2,
    "day": 2,
    "leap_month": false,
    "days_in_month": 29,
    "zodiac": "horse",
    "year_pillar": "bing_wu",
    "day_pillar": "gui_si",
    "method": "hko_gbt33661"
  }
}

20 March 2026 is day 1 of Shawwal in the Umm al-Qura calendar. Indonesia's authority started Shawwal on 21 March, so the same civil day is day 30 of Ramadan there, and official.day is 30. Only the calendars you list come back.

Convert a date

GET /v1/calendars/dates/{date} returns one Gregorian date in each calendar named in calendars. A date means the native day in force during the daytime of that civil day. If any requested calendar cannot answer, the whole request fails with one error that names each calendar, and nothing is returned for the others.

Parameters

NameTypeRule
datedate, in the pathRequired. YYYY-MM-DD, from 1900-01-01 to 2200-12-31. Each calendar then checks its own range.
calendarsstringRequired. Calendar keys separated by commas: 1 to 13 keys, each once, at most 200 characters. The keys are chinese, vietnamese, korean, japanese, hijri, persian, hindu, tamil, malayalam, bengali, odia, nepali and indian_national.
countrystringOnly with hijri. ISO 3166-1 alpha-3 code, one of IDN, SAU, MYS, TUR, EGY and PAK. Adds the official Hijri day of that country in an official block. Another ISO code returns 404 not_covered. A value that is not an ISO 3166-1 alpha-3 code in capital letters returns 400.
after_sunsetbooleanOnly with hijri. true gives the Hijri day that begins at sunset of the civil day, which is the next Hijri day. Default false. Accepts true, false, 1, 0, yes, no, on, off, t, f, y and n.
adjustmentintegerOnly with hijri. -2 to 2 days added to the Umm al-Qura date. Default 0. The official block is not adjusted.
schemestringOnly with hindu. amanta or purnimanta. Default amanta.
ayanamsastringOnly with hindu. lahiri, the only value.
lat / lonnumberOnly with hindu. Latitude from -90 to 90 and longitude from -180 to 180. Send both or neither. Neither means New Delhi.
tzstringOnly with hindu. An IANA time zone name of 1 to 64 characters. See Place and time zone below.

A parameter sent without the calendar it belongs to is a 400 error, and so is a parameter that is not listed.

A Hindu date is read at local sunrise, so it needs a place. This request reads 8 November 2026 at Auckland and adds the Tamil solar date
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/2026-11-08?calendars=hindu,tamil&lat=-36.8485&lon=174.7633&tz=Pacific/Auckland" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "date": "2026-11-08",
  "hindu": {
    "vikram_samvat": 2083,
    "shaka_samvat": 1948,
    "month": "ashwina",
    "month_number": 7,
    "adhika": false,
    "paksha": "krishna",
    "tithi": 14,
    "days_in_month": 30,
    "scheme": "amanta",
    "location": {
      "lat": -36.8485,
      "lon": 174.7633,
      "timezone": "Pacific/Auckland"
    },
    "method": "jpl_de440_lahiri"
  },
  "tamil": {
    "year": 1948,
    "month": 7,
    "day": 22,
    "days_in_month": 30,
    "era": "saka",
    "method": "sankranti_tamil_v1"
  }
}

Response fields

The answer holds the date you sent and one block for each calendar you listed. The blocks are:

BlockFieldsMeaning
chinese / vietnamese / koreanyear, month, day, leap_month, days_in_month, zodiac, year_pillar, day_pillar, methodLunisolar date. year is the lunar year, month is 1 to 12, leap_month is true in a leap month, days_in_month is 29 or 30. zodiac is an English animal name (Vietnamese uses buffalo for ox and cat for rabbit). year_pillar and day_pillar are a stem and a branch in lowercase pinyin, such as bing_wu.
japanesethe lunisolar fields, and eraThe old Japanese calendar. era is { key, year } with key meiji, taisho, showa, heisei or reiwa, and year 1 for the first year of the era.
hijriyear, month, day, days_in_month, after_sunset, adjustment, method, officialUmm al-Qura date. days_in_month is 29 or 30. after_sunset and adjustment repeat what was applied. official is { country, day, status } and is present whenever country was sent. day is null while status is calculated. status is calculated, published or announced.
persianyear, month, day, days_in_month, methodPersian solar date. days_in_month is 29 to 31.
hinduvikram_samvat, shaka_samvat, month, month_number, adhika, paksha, tithi, days_in_month, scheme, location, methodHindu lunisolar date of the civil day, read at local sunrise at location ({ lat, lon, timezone }). month is the lunar month key, chaitra to phalguna, and month_number is 1 to 12. adhika is true in a repeated month, which carries the name of the month that follows it. paksha is shukla or krishna. tithi is 1 to 15 within the paksha. days_in_month counts the days with a sunrise in the month. With purnimanta the krishna paksha carries the name of the next month. The two samvat numbers turn on the shukla pratipada of the regular Chaitra, whatever the scheme.
tamil / malayalam / bengali / odia / nepali / indian_nationalyear, month, day, days_in_month, era, methodSolar date. Month 1 is the first month of the calendar's year (Chithirai, Chingam, Boishakh, Baisakha, Baisakh and Chaitra in that order). era is saka, kollam, bangabda, saka, bikram_sambat and saka in that order, and the year turns at month 1. days_in_month is 28 to 32.

method names the rule that produced the block. The values are in the table of calendars below.

Find a date

GET /v1/calendars/dates/from/{calendar} returns the Gregorian date of a date written in another calendar. The native date goes in the query, because YYYY-MM-DD cannot hold a leap month, an adhika month, a paksha or an era. dates is always a list. A day the calendar does not have, such as day 30 of a 29-day Hijri month, returns 422 non_existent_date. It is never moved to another day.

The first day of the Chinese year 2026
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/from/chinese?year=2026&month=1&day=1" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "calendar": "chinese",
  "dates": [
    "2026-02-17"
  ],
  "method": "hko_gbt33661"
}

Parameters

calendar in the path is required and is one of the thirteen keys. The other parameters depend on the calendar. A missing required parameter returns 400 with the detail chinese needs day, month, year, with the names in alphabetical order. A parameter the calendar does not use returns 400 with the detail lat does not apply to persian.

CalendarRequiredOptional
chinese / vietnamese / korean / japaneseyear, month, dayleap_month
hijriyear, month, dayadjustment, country
persian / tamil / malayalam / bengali / odia / nepali / indian_nationalyear, month, dayNone
hinduyear, era, month_key, paksha, dayadhika, scheme, ayanamsa, lat, lon, tz
NameTypeRule
yearinteger1 to 9999. The year in the calendar's own count: the lunar year, the AH year, the Persian year, the Saka, Kollam, Bangabda or Bikram Sambat year, or for hindu the year of the era you send. A year outside the calendar's range returns 422 out_of_range.
monthinteger1 to 12. Not used by hindu, which takes month_key.
dayinteger1 to 32. For hindu it is the tithi, 1 to 15 within the paksha. A day above 15 returns 400.
leap_monthbooleanLunisolar calendars. true asks for the leap month. Default false.
adjustmentintegerOnly hijri. -2 to 2 days, the same shift as in the conversion route. Default 0.
countrystringOnly hijri. One of IDN, SAU, MYS, TUR, EGY and PAK. Adds an official block.
erastringOnly hindu, required. vikram or shaka.
month_keystringOnly hindu, required. chaitra, vaishakha, jyeshtha, ashadha, shravana, bhadrapada, ashwina, kartika, margashirsha, pausha, magha or phalguna.
pakshastringOnly hindu, required. shukla or krishna.
adhikabooleanOnly hindu. true asks for the repeated month. Default false.
scheme / ayanamsastringOnly hindu. amanta or purnimanta, default amanta. lahiri, the only ayanamsa.
lat / lon / tznumber, number, stringOnly hindu. The place the sunrise is computed for. Same rules as in the conversion route: see Place and time zone below.
Ugadi 2026: Chaitra, shukla paksha, tithi 1, of Vikram year 2083, read at New Delhi
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/from/hindu?era=vikram&year=2083&month_key=chaitra&paksha=shukla&day=1" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "calendar": "hindu",
  "dates": [
    "2026-03-19"
  ],
  "kshaya": true,
  "method": "jpl_de440_lahiri"
}

That pratipada is skipped: no sunrise falls inside it. dates holds the one civil day it runs in and kshaya is true. A tithi that covers two sunrises returns two dates.

Response fields

FieldTypeMeaning
calendarstringThe calendar key you sent.
datesdate arrayGregorian dates, YYYY-MM-DD. One date for every calendar but hindu, which can return two.
kshayabooleanOnly hindu, and only when true: the tithi is skipped. Left out otherwise.
officialobjectOnly hijri with country: { country, dates, status }. dates holds the official Gregorian day, or is empty while the country has no official value for that month or when the day falls after the official end of the month. status is calculated, published or announced.
methodstringThe rule that produced the date. The values are in the table of calendars below.

Official Hijri months

GET /v1/calendars/hijri/{country}/{year} returns the twelve months of one Hijri year for a country, with the calculated first day of each month and, where the country's authority has decided, the official first day. The calculated day comes from the Umm al-Qura table. Countries differ from it by a day in some months, as the example shows.

The Hijri year 1447 in Indonesia
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/hijri/IDN/1447" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK, trimmed to months 1 and 10. The real answer has twelve months.
{
  "country": "IDN",
  "year": 1447,
  "months": [
    {
      "month": 1,
      "calculated_start": "2025-06-26",
      "official_start": null,
      "status": "calculated",
      "source": null,
      "source_url": null,
      "authority": "Kementerian Agama (Kemenag), Sidang Isbat for Ramadan, Shawwal and Dhu al-Hijjah",
      "announced_on": null,
      "decision_expected_on": null,
      "revised": false,
      "updated_at": "2026-10-30T00:00:00Z"
    },
    {
      "month": 10,
      "calculated_start": "2026-03-20",
      "official_start": "2026-03-21",
      "status": "published",
      "source": "kemenag_table",
      "source_url": "https://aceh.kemenag.go.id/storage/berita_informasi/01K7GE96M0ZVRJ62Z520RMYG1B.pdf",
      "authority": "Kementerian Agama (Kemenag), Sidang Isbat for Ramadan, Shawwal and Dhu al-Hijjah",
      "announced_on": null,
      "decision_expected_on": "2026-03-18",
      "revised": false,
      "updated_at": "2026-11-02T16:31:12.279058Z"
    }
  ]
}

Parameters

NameTypeRule
countrystring, in the pathRequired. One of IDN, SAU, MYS, TUR, EGY and PAK. Another ISO code returns 404 not_covered. A value that is not an ISO 3166-1 alpha-3 code in capital letters returns 400.
yearinteger, in the pathRequired. The Hijri (AH) year, 1356 to 1500. Another number returns 422 out_of_range with the detail Hijri years run from AH 1356 to 1500. Text that is not a whole number returns 400.

Response fields

The answer is { country, year, months }, with months always holding 12 objects in month order.

FieldTypeMeaning
monthinteger1 to 12.
calculated_startdateGregorian first day of the month by the Umm al-Qura table.
official_startdate or nullThe official first day. null only while status is calculated.
statusstringcalculated: no official value yet. published: an official yearly table, which can still change. announced: the final sighting or isbat decision.
sourcestring or nullWhere the official value comes from: kemenag_isbat, kemenag_table, umm_al_qura_civil, sa_supreme_court, jakim, diyanet, dar_al_ifta or ruet_e_hilal. null while calculated.
source_urlstring or nullLink to that source. null while calculated.
authoritystring or nullThe body that decides the month for the country. See the list below.
announced_ondate or nullThe day the decision was announced, when recorded.
decision_expected_ondate or nullThe evening the sighting is expected, which is day 29 of the month before. null when no decision is expected: the authority announces none for that month, or the country has no feed.
no_feedbooleanPresent and true only for Egypt and Pakistan. Narwhal has no feed for them, so a month stays calculated until an announcement is recorded and no decision date is given.
revisedbooleantrue when the value changed after it was first published.
updated_atdate-timeWhen the month's record was last updated. For a month that is still calculated it is a fixed date for the calculated table, not a time the data was checked.
CountryAuthority named in authorityMonths that carry decision_expected_on
IDNKementerian Agama (Kemenag), Sidang Isbat for Ramadan, Shawwal and Dhu al-Hijjah9, 10 and 12
SAUUmm al-Qura calendar (civil months). For months 9, 10 and 12 the Supreme Court of Saudi Arabia (moon sighting).9, 10 and 12
MYSPenyimpan Mohor Besar Raja-Raja (calendar published by JAKIM)9, 10 and 12
TURDiyanet Isleri Baskanligi (calculated years ahead)None
EGYDar al-Ifta al-MisriyyahNone, no feed
PAKCentral Ruet-e-Hilal CommitteeNone, no feed

The answer carries an ETag. Send it back in If-None-Match. While nothing has changed the API answers 304 with no body, and the call costs nothing. A year that ended more than 30 days ago is cached for a day (Cache-Control: private, max-age=86400) and any other year for five minutes.

Calendars and ranges

Each calendar covers a range of Gregorian dates and names its method. A date outside the range returns 422 out_of_range, and the detail gives the range.

KeyCalendarCoversmethod
chineseChinese lunisolar1901-01-01 to 2100-12-31hko_gbt33661
vietnameseVietnamese lunisolar1901-01-01 to 2200-12-06gbt33661_vn_clock
koreanKorean lunisolar1901-01-01 to 2200-12-06gbt33661_kasi_clock
japaneseJapanese old calendar, with era1901-01-01 to 2200-12-06gbt33661_jst
hijriHijri, Umm al-Qura1937-03-14 to 2077-11-16 (AH 1356 to 1500), after any after_sunset or adjustmentumm_al_qura, or umm_al_qura+adj when adjustment is not 0
persianPersian solar1900-01-01 to 2200-12-31arithmetic_33
hinduHindu lunisolar, Lahiri1900-01-02 to 2200-12-21jpl_de440_lahiri
tamilTamil solar1900-01-13 to 2200-12-18sankranti_tamil_v1
malayalamMalayalam solar1900-01-13 to 2200-12-18sankranti_malayalam_v1
bengaliBengali solar1900-01-14 to 2200-12-19sankranti_west_bengal_v1
odiaOdia solar1900-01-13 to 2200-12-18sankranti_odia_v1
nepaliNepali, Bikram Sambat1921-04-13 to 2027-04-13nepal_panchanga_tables
indian_nationalIndian national, Saka1900-01-01 to 2200-12-31indian_national_fixed

The lunisolar dates are checked against published tables to 2100, and the Korean dates to 2050. After 2100 a date can differ by a day from another computation when a new moon falls within about a minute of local midnight. A leap month is the first month after the winter solstice month that has no major solar term (GB/T 33661-2017).

Place and time zone

Only the Hindu calendar depends on a place, because its tithi, paksha and month are read at the sunrise of the civil day. The Sun's upper edge counts as risen, with 34 arcminutes of refraction. The parameters are lat, lon and tz, in the conversion route and in the find route.

You sendThe API readsResult
None of lat, lon and tzNew Delhi, 28.6139 and 77.209, on Asia/Kolkata200
lat and lon with tzThat place on that time zone200
lat and lon without tzNothing. No time zone is guessed from coordinates.422 time_zone_required
tz other than Asia/Kolkata, without lat and lonNothing. Without coordinates it would be the New Delhi sunrise on another clock.422 location_required
tz set to Asia/Kolkata, without lat and lonNew Delhi on Asia/Kolkata200
lat without lon, or the reverseNothing.400 invalid_query
tz that is not an IANA nameNothing.400 invalid_query
A place where the Sun does not rise or does not set on that dayNothing. The detail says midnight sun or polar night.422 no_sunrise

lat and tz sent without hindu in calendars return 400, and so do lat and tz on a find request for any other calendar. The hindu block repeats the place it used in location.

Matching MCP call

Send an authenticated POST /mcp with Accept: application/json, text/event-stream. The three tools are read-only and take the parameter names above: calendars_convert_dates with date and calendars, calendars_find_dates with calendar and the native date, and calendars_get_hijri_year with country and year.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendars_convert_dates",
    "arguments": {
      "date": "2026-03-20",
      "calendars": "hijri,chinese",
      "country": "IDN"
    }
  }
}

Successful results have isError: false, the same response in structuredContent, and serialized JSON in content[0].text. Domain errors have isError: true.

Errors and credits

StatusCodeWhen
400invalid_queryA parameter is missing, out of its limits or not listed. A parameter is sent without the calendar it belongs to. Only one of lat and lon is sent. A find request lacks a parameter its calendar needs or has one it does not use. A Hindu day is above 15. The detail lists every failed check, separated by semicolons, each starting with path. or query.
401invalid_api_keyThe key is missing or invalid.
402insufficient_creditsThe balance cannot pay for the call. The answer carries top_up_url.
404not_coveredcountry is a valid ISO code but not one of IDN, SAU, MYS, TUR, EGY and PAK. Not charged.
422out_of_rangeThe date or year is outside the range of a calendar. The detail gives the range. A date outside 1900-01-01 to 2200-12-31 returns the detail Dates run from 1900-01-01 to 2200-12-31.
422non_existent_dateThe calendar has no such day, for example day 30 of a 29-day month, a leap month the year does not have, or an adhika month the Hindu year does not have. The detail says why.
422no_sunriseThe Sun does not rise or does not set at the place on that day, so a Hindu date has no sunrise to read.
422time_zone_requiredlat and lon were sent without tz. The detail begins Send tz (an IANA time zone such as Pacific/Auckland) with lat and lon.
422location_requiredtz other than Asia/Kolkata was sent without lat and lon. The detail begins Send lat and lon with a tz other than Asia/Kolkata.
429rate_limit_exceededThe per-minute limit is reached.
503database_unavailableThe data store is temporarily unavailable. Retry shortly.

Error examples

Two failed checks in one request
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/2026-11-08?calendars=hijri,hijri&adjustment=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
400 Bad Request
{
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "query.calendars: Value error, each calendar may appear once; query.adjustment: Input should be less than or equal to 2",
  "code": "invalid_query",
  "request_id": "6170490e-f65e-4778-88ce-0691ca7246b8"
}
Two calendars out of range: one error names both
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/2150-01-01?calendars=chinese,hijri" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
422 Unprocessable Content
{
  "type": "https://narwhalapi.com/problems/out-of-range",
  "title": "Date out of range",
  "status": 422,
  "detail": "chinese covers 1901-01-01 to 2100-12-31. hijri covers 1937-03-14 to 2077-11-16.",
  "code": "out_of_range",
  "request_id": "5c0a034a-1b6b-42bf-a64f-509916d6d9f4"
}
Day 30 of a Hijri month that has 29 days
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/from/hijri?year=1447&month=2&day=30" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
422 Unprocessable Content
{
  "type": "https://narwhalapi.com/problems/non-existent-date",
  "title": "Date does not exist",
  "status": 422,
  "detail": "Hijri month 2 of 1447 has 29 days.",
  "code": "non_existent_date",
  "request_id": "164aae51-bdd5-4f9c-a3fb-743d15b14d4a"
}
Midnight sun at Svalbard on the June solstice
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/dates/2026-06-21?calendars=hindu&lat=78.22&lon=15.65&tz=Arctic/Longyearbyen" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
422 Unprocessable Content
{
  "type": "https://narwhalapi.com/problems/no-sunrise",
  "title": "No sunrise",
  "status": 422,
  "detail": "The Sun does not set (midnight sun) on 2026-06-21 at this latitude, so there is no sunrise and no tithi at sunrise.",
  "code": "no_sunrise",
  "request_id": "2daae5a5-1e28-418f-8184-1306c92d9dc3"
}
A country without an official Hijri authority in this list
curl --request GET \
  --url "https://api.narwhalapi.com/v1/calendars/hijri/USA/1447" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
404 Not Found
{
  "type": "https://narwhalapi.com/problems/not-covered",
  "title": "Country not covered",
  "status": 404,
  "detail": "Official Hijri dates are published for IDN, SAU, MYS, TUR, EGY, PAK.",
  "code": "not_covered",
  "request_id": "0634df8a-3045-4f5c-b2b9-b8ab1b8cf74f"
}

A successful request costs one call on the Calendars API code, $2 per 1,000 calls, however many calendars it lists. Errors cost nothing, and so does a Hijri year answered with 304. Successful answers carry Cache-Control private. Convert and find answers are cached for a day, or for five minutes when country is sent. Errors are not cached. Shared error details

Exchange closures · Public holidays reference

Was this page helpful?