Name: Calendar Converter API: Hijri, Hebrew and Chinese
Brand: tidydata
SKU: api-tidydata-calendar-converter
Availability: InStock
Author: API Market

TidyData

# Calendar Converter API

## Overview

The Calendar Converter API converts dates between the Gregorian calendar and 12 others: Islamic Umm al-Qura and Islamic tabular, Hebrew, Persian (Solar Hijri), Chinese, Korean (Dangi), Japanese, Buddhist (Thai), Indian National (Saka), Coptic, Ethiopian and Minguo (Taiwan). It has four endpoints. /v1/calendar/convert shows one Gregorian date in every calendar or in the ones you list, /v1/calendar/to-gregorian converts a date from any calendar back to Gregorian, /v1/calendar/events returns the dates of major Islamic, Jewish, Chinese and Persian holidays for a year from 1900 to 2100, and /v1/calendar/list returns the calendar ids the other endpoints accept.

Converted dates come back with year, month number and month name, day, era and a formatted string such as 1 Heshvan 5787 AM, along with the weekday. Holiday results include the Gregorian date, weekday and the date in the local calendar, for events such as Ramadan, Eid al-Fitr, Eid al-Adha, Islamic New Year, Rosh Hashanah, Yom Kippur, Passover, Hanukkah, Chinese New Year, the Mid-Autumn Festival and Nowruz. The API uses the ICU calendar engine, and the seller checks Chinese month starts against astronomical new moons. It is aimed at scheduling and HR software for global teams, marketing and e-commerce calendars, travel apps, and religious and community apps.

## Features

*   **Four endpoints**: Convert from Gregorian, convert to Gregorian, list religious and cultural holidays, and list supported calendars.
*   **13 calendars**: Gregorian, Islamic Umm al-Qura, Islamic tabular, Hebrew, Persian, Chinese, Korean, Japanese, Buddhist, Indian National, Coptic, Ethiopian and Minguo.
*   **Two way conversion**: Go from a Gregorian date to every calendar at once, or from a date in any calendar back to Gregorian.
*   **Holiday dates 1900 to 2100**: Islamic, Jewish, Chinese and Persian holidays for any year in range, filterable by type.
*   **Readable output**: Each converted date includes month names, era and a formatted string ready to display.
*   **Calendar filter**: Pass a comma separated calendars list on the convert endpoint to return only the calendars you need.
*   **10 requests per second**: All plans allow up to 10 requests per second.

## Use Cases

*   **Scheduling and HR for global teams**: Plan around Ramadan, Jewish holidays, Chinese New Year and Nowruz when setting meetings, shifts and leave.
*   **Marketing and e-commerce calendars**: Pull the exact dates of Eid, Chinese New Year or Mid-Autumn each year to schedule campaigns and promotions.
*   **Date pickers with local calendars**: Show the Hijri, Hebrew or Persian date next to the Gregorian date in forms and booking flows.
*   **Religious and community apps**: Convert birthdays, anniversaries and observances between calendars and list upcoming holidays.
*   **Travel apps**: Warn travelers about public holiday periods tied to lunar or lunisolar calendars at their destination.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/tidydata/calendar-converter
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Convert a Gregorian date to other calendars

Returns one Gregorian date (default today) in every supported calendar, or only those named in calendars, with year, month, month name, day, era and a formatted string.

**Method:** `GET`

**Endpoint:** `/v1/calendar/convert`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `date` | query | Gregorian date YYYY-MM-DD (default: today) | string | No | - | - |
| `calendars` | query | Optional comma list of calendar ids | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/calendar-converter/v1/calendar/convert?date=2026-10-12&calendars=hebrew%2Cislamic-umalqura%2Cpersian" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "gregorianDate": "2026-10-12",
  "weekday": "Monday",
  "calendars": [
    {
      "calendar": "hebrew",
      "name": "Hebrew",
      "year": 5787,
      "month": "Heshvan",
      "monthName": "Heshvan",
      "day": 1,
      "era": "AM",
      "formatted": "1 Heshvan 5787 AM"
    },
    {
      "calendar": "islamic-umalqura",
      "name": "Islamic (Umm al-Qura)",
      "year": 1448,
      "month": 5,
      "monthName": "Jumada I",
      "day": 1,
      "era": "AH",
      "formatted": "Jumada I 1, 1448 AH"
    },
    {
      "calendar": "persian",
      "name": "Persian (Solar Hijri)",
      "year": 1405,
      "month": 7,
      "monthName": "Mehr",
      "day": 20,
      "era": "AP",
      "formatted": "Mehr 20, 1405 AP"
    }
  ]
}
```

#### 2. Convert a date to Gregorian

Converts a year, month and day in any supported calendar to the Gregorian date and weekday. Hebrew months are passed by name, for example Nisan.

**Method:** `GET`

**Endpoint:** `/v1/calendar/to-gregorian`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `calendar` | query | Calendar id | string | Yes | - | - |
| `year` | query | Year in that calendar | string | Yes | - | - |
| `month` | query | Month number (Hebrew: name, e.g. Nisan) | string | Yes | - | - |
| `day` | query | Day of month | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/calendar-converter/v1/calendar/to-gregorian?calendar=hebrew&year=5787&month=Nisan&day=15" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "input": {
    "calendar": "hebrew",
    "year": 5787,
    "month": "Nisan",
    "day": 15
  },
  "gregorianDate": "2027-04-22",
  "weekday": "Thursday"
}
```

#### 3. Get religious and cultural holidays

Lists Islamic, Jewish, Chinese and Persian holidays for a Gregorian year from 1900 to 2100, with the Gregorian date, weekday and local calendar date. Use type to return one group only.

**Method:** `GET`

**Endpoint:** `/v1/calendar/events`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `year` | query | Gregorian year 1900-2100 | string | Yes | - | - |
| `type` | query | all, islamic, jewish, chinese or persian | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/calendar-converter/v1/calendar/events?year=2027&type=all" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "year": 2027,
  "islamic": {
    "calendar": "islamic-umalqura",
    "note": "Umm al-Qura calendar (Saudi Arabia). Dates in other countries may differ by a day depending on moon sighting; Islamic days begin at sunset the evening before.",
    "events": [
      {
        "name": "Isra and Miraj",
        "date": "2027-01-05",
        "weekday": "Tuesday",
        "local": "Rajab 27, 1448 AH"
      },
      {
        "name": "Ramadan begins",
        "date": "2027-02-08",
        "weekday": "Monday",
        "local": "Ramadan 1, 1448 AH"
      },
      {
        "name": "Laylat al-Qadr",
        "date": "2027-03-06",
        "weekday": "Saturday",
        "local": "Ramadan 27, 1448 AH"
      }
    ]
  },
  "jewish": {
    "calendar": "hebrew",
    "note": "Jewish holidays begin at sunset on the evening before the listed date.",
    "events": [
      {
        "name": "Tu BiShvat",
        "date": "2027-01-23",
        "weekday": "Saturday",
        "local": "15 Shevat 5787"
      },
      {
        "name": "Purim",
        "date": "2027-03-23",
        "weekday": "Tuesday",
        "local": "14 Adar II 5787"
      },
      {
        "name": "Passover",
        "date": "2027-04-22",
        "weekday": "Thursday",
        "local": "15 Nisan 5787"
      }
    ]
  },
  "chinese": {
    "calendar": "chinese",
    "note": "Traditional Chinese lunisolar calendar (China Standard Time). Month starts are verified against precise astronomical new moons.",
    "events": [
      {
        "name": "Chinese New Year (Spring Festival)",
        "date": "2027-02-06",
        "weekday": "Saturday",
        "local": "Twelfth Month 30, 2026(bing-wu)"
      },
      {
        "name": "Lantern Festival",
        "date": "2027-02-20",
        "weekday": "Saturday",
        "local": "First Month 14, 2027(ding-wei)"
      },
      {
        "name": "Dragon Boat Festival",
        "date": "2027-06-09",
        "weekday": "Wednesday",
        "local": "Fifth Month 5, 2027(ding-wei)"
      }
    ]
  },
  "persian": {
    "calendar": "persian",
    "note": "Solar Hijri calendar.",
    "events": [
      {
        "name": "Nowruz (Persian New Year)",
        "date": "2027-03-21",
        "weekday": "Sunday",
        "local": "Farvardin 1, 1406 AP"
      },
      {
        "name": "Sizdah Bedar",
        "date": "2027-04-02",
        "weekday": "Friday",
        "local": "Farvardin 13, 1406 AP"
      }
    ]
  }
}
```

#### 4. List supported calendars

Returns the id and display name of each of the 13 calendars, for use in the calendars and calendar parameters.

**Method:** `GET`

**Endpoint:** `/v1/calendar/list`

**Parameters:** none.

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/calendar-converter/v1/calendar/list" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "calendars": [
    {
      "id": "gregorian",
      "name": "Gregorian"
    },
    {
      "id": "islamic-umalqura",
      "name": "Islamic (Umm al-Qura)"
    },
    {
      "id": "islamic-civil",
      "name": "Islamic (tabular)"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the result is in the response body. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. The body explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The requested item or path does not exist. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Every plan allows 10 requests per second. The Pro plan includes 25,000 calls a month and the Ultra plan 150,000; when a monthly quota is used up, further calls return `429 Too Many Requests` until the next billing period. The pay-as-you-go plan has no quota and bills US$0.0005 per successful call. If you receive a `429`, back off before retrying and honour any `Retry-After` header.

## FAQ

**Which calendar ids can I use?**

gregorian, islamic-umalqura, islamic-civil, hebrew, persian, chinese, dangi, japanese, buddhist, indian, coptic, ethiopic and roc. Call /v1/calendar/list for the current list with display names.

**How do I pass a Hebrew month to to-gregorian?**

Hebrew months are passed by name rather than number, for example month=Nisan. 15 Nisan 5787 returns 2027-04-22, a Thursday. Other calendars take the month number.

**Why might an Islamic holiday date differ from my local announcement?**

Islamic dates follow the Umm al-Qura calendar used in Saudi Arabia. Other countries that rely on moon sighting can be a day apart, and Islamic days begin at sunset the evening before the listed date.

**Do Jewish holidays start on the listed date?**

Jewish holidays begin at sunset on the evening before the listed Gregorian date, as the response note states.

**Which years are supported for holidays?**

The events endpoint accepts Gregorian years from 1900 to 2100. Use type=islamic, jewish, chinese or persian to return one group, or all for every group.

**What happens if I call convert without a date?**

The date parameter defaults to today, so the endpoint returns today's date in every calendar.

**How much does the Calendar Converter API cost?**

There is no free plan. Pay as you go costs US$0.0005 per call with no monthly fee. Pro is US$4.99 per month for 25,000 calls and Ultra is US$14.99 per month for 150,000 calls. All plans allow 10 requests per second.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Calendar converter API for 13 calendars: Gregorian to Hijri, Hebrew, Persian, Chinese and more, back to Gregorian, plus holiday dates for 1900 to 2100.