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.
| Operation | GET endpoint | MCP tool |
|---|---|---|
| Convert a date to other calendars | GET / | calendars_ |
| Find the Gregorian date of a date in another calendar | GET / | calendars_ |
| Read the official Hijri months of a country and year | GET / | calendars_ |
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"{
"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 / 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
| Name | Type | Rule |
|---|---|---|
date | date, in the path | Required. YYYY-MM-DD, from 1900-01-01 to 2200-12-31. Each calendar then checks its own range. |
calendars | string | Required. 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. |
country | string | Only 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_ | boolean | Only 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. |
adjustment | integer | Only with hijri. -2 to 2 days added to the Umm al-Qura date. Default 0. The official block is not adjusted. |
scheme | string | Only with hindu. amanta or purnimanta. Default amanta. |
ayanamsa | string | Only with hindu. lahiri, the only value. |
lat / | number | Only with hindu. Latitude from -90 to 90 and longitude from -180 to 180. Send both or neither. Neither means New Delhi. |
tz | string | Only 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.
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"{
"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:
| Block | Fields | Meaning |
|---|---|---|
chinese / | year, month, day, leap_ | Lunisolar 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. |
japanese | the lunisolar fields, and era | The 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. |
hijri | year, month, day, days_ | Umm 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. |
persian | year, month, day, days_ | Persian solar date. days_in_month is 29 to 31. |
hindu | vikram_ | Hindu 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 / | year, month, day, days_ | Solar 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 / 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_. It is never moved to another day.
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"{
"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.
| Calendar | Required | Optional |
|---|---|---|
chinese / | year, month, day | leap_ |
hijri | year, month, day | adjustment, country |
persian / | year, month, day | None |
hindu | year, era, month_ | adhika, scheme, ayanamsa, lat, lon, tz |
| Name | Type | Rule |
|---|---|---|
year | integer | 1 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. |
month | integer | 1 to 12. Not used by hindu, which takes month_key. |
day | integer | 1 to 32. For hindu it is the tithi, 1 to 15 within the paksha. A day above 15 returns 400. |
leap_ | boolean | Lunisolar calendars. true asks for the leap month. Default false. |
adjustment | integer | Only hijri. -2 to 2 days, the same shift as in the conversion route. Default 0. |
country | string | Only hijri. One of IDN, SAU, MYS, TUR, EGY and PAK. Adds an official block. |
era | string | Only hindu, required. vikram or shaka. |
month_ | string | Only hindu, required. chaitra, vaishakha, jyeshtha, ashadha, shravana, bhadrapada, ashwina, kartika, margashirsha, pausha, magha or phalguna. |
paksha | string | Only hindu, required. shukla or krishna. |
adhika | boolean | Only hindu. true asks for the repeated month. Default false. |
scheme / | string | Only hindu. amanta or purnimanta, default amanta. lahiri, the only ayanamsa. |
lat / | number, number, string | Only hindu. The place the sunrise is computed for. Same rules as in the conversion route: see Place and time zone below. |
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"{
"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
| Field | Type | Meaning |
|---|---|---|
calendar | string | The calendar key you sent. |
dates | date array | Gregorian dates, YYYY-MM-DD. One date for every calendar but hindu, which can return two. |
kshaya | boolean | Only hindu, and only when true: the tithi is skipped. Left out otherwise. |
official | object | Only 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. |
method | string | The rule that produced the date. The values are in the table of calendars below. |
Official Hijri months
GET / 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.
curl --request GET \
--url "https://api.narwhalapi.com/v1/calendars/hijri/IDN/1447" \
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"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
| Name | Type | Rule |
|---|---|---|
country | string, in the path | Required. 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. |
year | integer, in the path | Required. 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.
| Field | Type | Meaning |
|---|---|---|
month | integer | 1 to 12. |
calculated_ | date | Gregorian first day of the month by the Umm al-Qura table. |
official_ | date or null | The official first day. null only while status is calculated. |
status | string | calculated: no official value yet. published: an official yearly table, which can still change. announced: the final sighting or isbat decision. |
source | string or null | Where 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_ | string or null | Link to that source. null while calculated. |
authority | string or null | The body that decides the month for the country. See the list below. |
announced_ | date or null | The day the decision was announced, when recorded. |
decision_ | date or null | The 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_ | boolean | Present 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. |
revised | boolean | true when the value changed after it was first published. |
updated_ | date-time | When 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. |
| Country | Authority named in authority | Months that carry decision_expected_on |
|---|---|---|
IDN | Kementerian Agama (Kemenag), Sidang Isbat for Ramadan, Shawwal and Dhu al-Hijjah | 9, 10 and 12 |
SAU | Umm al-Qura calendar (civil months). For months 9, 10 and 12 the Supreme Court of Saudi Arabia (moon sighting). | 9, 10 and 12 |
MYS | Penyimpan Mohor Besar Raja-Raja (calendar published by JAKIM) | 9, 10 and 12 |
TUR | Diyanet Isleri Baskanligi (calculated years ahead) | None |
EGY | Dar al-Ifta al-Misriyyah | None, no feed |
PAK | Central Ruet-e-Hilal Committee | None, 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.
| Key | Calendar | Covers | method |
|---|---|---|---|
chinese | Chinese lunisolar | 1901-01-01 to 2100-12-31 | hko_ |
vietnamese | Vietnamese lunisolar | 1901-01-01 to 2200-12-06 | gbt33661_ |
korean | Korean lunisolar | 1901-01-01 to 2200-12-06 | gbt33661_ |
japanese | Japanese old calendar, with era | 1901-01-01 to 2200-12-06 | gbt33661_ |
hijri | Hijri, Umm al-Qura | 1937-03-14 to 2077-11-16 (AH 1356 to 1500), after any after_sunset or adjustment | umm_, or umm_ when adjustment is not 0 |
persian | Persian solar | 1900-01-01 to 2200-12-31 | arithmetic_ |
hindu | Hindu lunisolar, Lahiri | 1900-01-02 to 2200-12-21 | jpl_ |
tamil | Tamil solar | 1900-01-13 to 2200-12-18 | sankranti_ |
malayalam | Malayalam solar | 1900-01-13 to 2200-12-18 | sankranti_ |
bengali | Bengali solar | 1900-01-14 to 2200-12-19 | sankranti_ |
odia | Odia solar | 1900-01-13 to 2200-12-18 | sankranti_ |
nepali | Nepali, Bikram Sambat | 1921-04-13 to 2027-04-13 | nepal_ |
indian_ | Indian national, Saka | 1900-01-01 to 2200-12-31 | indian_ |
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 send | The API reads | Result |
|---|---|---|
| None of lat, lon and tz | New Delhi, 28.6139 and 77.209, on Asia/Kolkata | 200 |
lat and lon with tz | That place on that time zone | 200 |
lat and lon without tz | Nothing. No time zone is guessed from coordinates. | 422 time_ |
tz other than Asia/Kolkata, without lat and lon | Nothing. Without coordinates it would be the New Delhi sunrise on another clock. | 422 location_ |
tz set to Asia/Kolkata, without lat and lon | New Delhi on Asia/Kolkata | 200 |
lat without lon, or the reverse | Nothing. | 400 invalid_ |
tz that is not an IANA name | Nothing. | 400 invalid_ |
| A place where the Sun does not rise or does not set on that day | Nothing. The detail says midnight sun or polar night. | 422 no_ |
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 / with Accept: application/. The three tools are read-only and take the parameter names above: calendars_ with date and calendars, calendars_ with calendar and the native date, and calendars_ 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
| Status | Code | When |
|---|---|---|
| 400 | invalid_ | A 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. |
| 401 | invalid_ | The key is missing or invalid. |
| 402 | insufficient_ | The balance cannot pay for the call. The answer carries top_up_url. |
| 404 | not_ | country is a valid ISO code but not one of IDN, SAU, MYS, TUR, EGY and PAK. Not charged. |
| 422 | out_ | The 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. |
| 422 | non_ | The 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. |
| 422 | no_ | The Sun does not rise or does not set at the place on that day, so a Hindu date has no sunrise to read. |
| 422 | time_ | lat and lon were sent without tz. The detail begins Send tz (an IANA time zone such as Pacific/Auckland) with lat and lon. |
| 422 | location_ | tz other than Asia/Kolkata was sent without lat and lon. The detail begins Send lat and lon with a tz other than Asia/Kolkata. |
| 429 | rate_ | The per-minute limit is reached. |
| 503 | database_ | The data store is temporarily unavailable. Retry shortly. |
Error examples
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"{
"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"
}curl --request GET \
--url "https://api.narwhalapi.com/v1/calendars/dates/2150-01-01?calendars=chinese,hijri" \
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"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"
}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"{
"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"
}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"{
"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"
}curl --request GET \
--url "https://api.narwhalapi.com/v1/calendars/hijri/USA/1447" \
--header "Authorization: Bearer $NARWHAL_API_KEY"{
"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
Was this page helpful?