---
title: "Calendar systems API | Narwhal API"
description: "Convert a date to the Chinese, Hijri, Persian, Hindu and other calendars, find a Gregorian date from a native one, and read official Hijri months. Parameters and errors."
url: "https://narwhalapi.com/docs/api/calendars/dates"
---

# 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 /v1/calendars/dates/{date}` | `calendars_convert_dates` |
| Find the Gregorian date of a date in another calendar | `GET /v1/calendars/dates/from/{calendar}` | `calendars_find_dates` |
| Read the official Hijri months of a country and year | `GET /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

| 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_sunset` | 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 / lon` | 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.

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:

| Block | Fields | Meaning |
| --- | --- | --- |
| `chinese / vietnamese / korean` | `year, month, day, leap_month, days_in_month, zodiac, year_pillar, day_pillar, method` | 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_in_month, after_sunset, adjustment, method, official` | 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_in_month, method` | Persian solar date. days_in_month is 29 to 31. |
| `hindu` | `vikram_samvat, shaka_samvat, month, month_number, adhika, paksha, tithi, days_in_month, scheme, location, method` | 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 / malayalam / bengali / odia / nepali / indian_national` | `year, month, day, days_in_month, era, method` | 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 /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`.

| Calendar | Required | Optional |
| --- | --- | --- |
| `chinese / vietnamese / korean / japanese` | `year, month, day` | `leap_month` |
| `hijri` | `year, month, day` | `adjustment, country` |
| `persian / tamil / malayalam / bengali / odia / nepali / indian_national` | `year, month, day` | None |
| `hindu` | `year, era, month_key, paksha, day` | `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_month` | 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_key` | 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 / ayanamsa` | string | Only hindu. amanta or purnimanta, default amanta. lahiri, the only ayanamsa. |
| `lat / lon / tz` | 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. |

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

| 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 /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

| 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_start` | date | Gregorian first day of the month by the Umm al-Qura table. |
| `official_start` | 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_url` | 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_on` | date or null | The day the decision was announced, when recorded. |
| `decision_expected_on` | 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_feed` | 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_at` | 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_gbt33661` |
| `vietnamese` | Vietnamese lunisolar | 1901-01-01 to 2200-12-06 | `gbt33661_vn_clock` |
| `korean` | Korean lunisolar | 1901-01-01 to 2200-12-06 | `gbt33661_kasi_clock` |
| `japanese` | Japanese old calendar, with era | 1901-01-01 to 2200-12-06 | `gbt33661_jst` |
| `hijri` | Hijri, Umm al-Qura | 1937-03-14 to 2077-11-16 (AH 1356 to 1500), after any after_sunset or adjustment | `umm_al_qura`, or `umm_al_qura+adj` when adjustment is not 0 |
| `persian` | Persian solar | 1900-01-01 to 2200-12-31 | `arithmetic_33` |
| `hindu` | Hindu lunisolar, Lahiri | 1900-01-02 to 2200-12-21 | `jpl_de440_lahiri` |
| `tamil` | Tamil solar | 1900-01-13 to 2200-12-18 | `sankranti_tamil_v1` |
| `malayalam` | Malayalam solar | 1900-01-13 to 2200-12-18 | `sankranti_malayalam_v1` |
| `bengali` | Bengali solar | 1900-01-14 to 2200-12-19 | `sankranti_west_bengal_v1` |
| `odia` | Odia solar | 1900-01-13 to 2200-12-18 | `sankranti_odia_v1` |
| `nepali` | Nepali, Bikram Sambat | 1921-04-13 to 2027-04-13 | `nepal_panchanga_tables` |
| `indian_national` | Indian national, Saka | 1900-01-01 to 2200-12-31 | `indian_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 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_zone_required` |
| `tz` other than Asia/Kolkata, without `lat` and `lon` | Nothing. Without coordinates it would be the New Delhi sunrise on another clock. | 422 `location_required` |
| `tz` set to Asia/Kolkata, without `lat` and `lon` | New Delhi on Asia/Kolkata | 200 |
| `lat` without `lon`, or the reverse | Nothing. | 400 `invalid_query` |
| `tz` that is not an IANA name | Nothing. | 400 `invalid_query` |
| 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_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

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_query` | 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_api_key` | The key is missing or invalid. |
| 402 | `insufficient_credits` | The balance cannot pay for the call. The answer carries top_up_url. |
| 404 | `not_covered` | country is a valid ISO code but not one of IDN, SAU, MYS, TUR, EGY and PAK. Not charged. |
| 422 | `out_of_range` | 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_existent_date` | 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_sunrise` | 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_zone_required` | 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_required` | 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_limit_exceeded` | The per-minute limit is reached. |
| 503 | `database_unavailable` | The 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](https://narwhalapi.com/docs/errors.md)
[Exchange closures](https://narwhalapi.com/docs/api/calendars/exchange-closures.md) · [Public holidays reference](https://narwhalapi.com/docs/api/calendars.md)

Was this page helpful?
