Persian Calendar API for developers

Today's date, date conversion, Iran's public holidays, occasions, the moment of Nowruz and prayer times as JSON: free, without keys.

Getting started

  • Base address: https://www.persian-calendar.com/api/
  • All requests are GET, and responses are JSON in UTF-8. No key or sign-up is needed.
  • Any site can call it from JavaScript in the browser (Access-Control-Allow-Origin: *).
  • Successful responses carry Cache-Control; please keep a response for that long.
  • A bad request gets a 422 response (and a year without data in nowruz a 404) with {"error": "…"}.
  • An app that calls the API from a server should put its name and its site or email address in the User-Agent header, such as MyApp/1.0 (https://example.com), so that we can reach you if a problem comes up.
  • Requests are counted for each site and app, and use that harms the site may be limited. A 429 response means the daily allowance is used up, and its Retry-After header gives the seconds left until the next day (Tehran time); a 403 response means access has been blocked. For heavy use, write to admin@persian-calendar.com.
  • Islamic dates follow Iran's official calendar. A future Islamic date not yet officially announced is an astronomical estimate and has estimate: true in the response (methodology).

Today's date GET /api/today

Today in four calendars, Persian, Gregorian, Islamic and Imperial, with the zodiac sign and the animal year.

ParameterStatusDescription
tzoptionalTime zone (IANA), e.g. Europe/London; Asia/Tehran by default

Example:

https://www.persian-calendar.com/api/today?tz=Asia/Tehran
{
    "timezone": "Asia/Tehran",
    "now": "2026-03-21T09:30:00+03:30",
    "sh": {
        "year": 1405,
        "month": 1,
        "day": 1,
        "month_name_fa": "فروردین",
        "month_name_en": "Farvardin",
        "weekday_fa": "شنبه",
        "weekday_en": "Saturday"
    }
}

The response is shortened: The rest is as in "Date converter": gregorian, hijri, pahlavi, zodiac and animal_year.

Date converter GET /api/convert

A date from any calendar, in all four.

ParameterStatusDescription
fromrequiredThe calendar of the date given: sh (Persian), gregorian, hijri or pahlavi
yearrequiredYear, in Latin or Persian digits
monthrequiredMonth, 1 to 12
dayrequiredDay

Example:

https://www.persian-calendar.com/api/convert?from=gregorian&year=2026&month=3&day=21
{
    "sh": {
        "year": 1405,
        "month": 1,
        "day": 1,
        "month_name_fa": "فروردین",
        "month_name_en": "Farvardin",
        "weekday_fa": "شنبه",
        "weekday_en": "Saturday"
    },
    "gregorian": {
        "year": 2026,
        "month": 3,
        "day": 21,
        "month_name_fa": "مارس",
        "month_name_en": "March",
        "weekday_fa": "شنبه",
        "weekday_en": "Saturday"
    },
    "hijri": {
        "year": 1447,
        "month": 10,
        "day": 1,
        "month_name_fa": "شوال",
        "month_name_en": "Shawwal",
        "weekday_fa": "شنبه",
        "weekday_en": "Saturday",
        "estimate": false
    },
    "pahlavi": {
        "year": 2585,
        "month": 1,
        "day": 1,
        "month_name_fa": "فروردین",
        "month_name_en": "Farvardin",
        "weekday_fa": "شنبه",
        "weekday_en": "Saturday"
    },
    "zodiac": {
        "symbol": "♈",
        "name_fa": "حَمَل",
        "name_en": "Aries"
    },
    "animal_year": {
        "name_fa": "اسب",
        "name_en": "Horse"
    }
}

Public holidays of a year GET /api/holidays

The public holidays of a Persian year in date order, each day with its occasions (sometimes two on one day).

ParameterStatusDescription
yearoptionalPersian year, 1347 or later; the current year by default

Example:

https://www.persian-calendar.com/api/holidays?year=1405
{
    "year": 1405,
    "data": [
        {
            "year_sh": 1405,
            "month_sh": 1,
            "day_sh": 1,
            "date_gregorian": "2026-03-21",
            "weekday_fa": "شنبه",
            "weekday_en": "Saturday",
            "estimate": false,
            "events": [
                {
                    "slug": "nowruz",
                    "title_fa": "نوروز - جشن آغاز سال نو",
                    "title_en": "Nowruz - New Year's Day",
                    "category": "national",
                    "is_holiday": true
                },
                {
                    "slug": "eid-al-fitr",
                    "title_fa": "عید سعید فطر",
                    "title_en": "Eid al-Fitr",
                    "category": "religious",
                    "is_holiday": true
                }
            ]
        }
    ]
}

The response is shortened: only the first of the 26 days is shown.

Occasions of a month or day GET /api/events

The national, religious, international and cultural occasions of a Persian month, or of one day of it.

ParameterStatusDescription
month_shrequiredPersian month, 1 to 12
yearoptionalPersian year; the current year by default
day_shoptionalJust one day of the month
categoryoptionalnational, religious, cultural, global, countries or fun

Example:

https://www.persian-calendar.com/api/events?year=1405&month_sh=1&day_sh=13
{
    "year": 1405,
    "data": [
        {
            "year_sh": 1405,
            "month_sh": 1,
            "day_sh": 13,
            "date_gregorian": "2026-04-02",
            "slug": "nature-day-sizdah-bedar",
            "title_fa": "روز طبیعت (سیزده‌بدر)",
            "title_en": "Nature Day (Sizdah Bedar)",
            "category": "national",
            "is_holiday": true
        }
    ]
}

Month grid GET /api/calendar

A six-week grid of a Persian month, weeks starting on Saturday, with each cell's date in four calendars and its occasions. The cells before and after the month are days of the neighbouring months.

ParameterStatusDescription
yearrequiredPersian year
monthrequiredPersian month, 1 to 12

Example:

https://www.persian-calendar.com/api/calendar?year=1405&month=1
{
    "year": 1405,
    "month": 1,
    "month_name_fa": "فروردین",
    "month_name_en": "Farvardin",
    "gregorian_span": "March – April 2026",
    "hijri_span": "شوال – ذی‌القعده ۱۴۴۷",
    "calendar": [
        [
            {
                "day": 1,
                "month": 1,
                "year": 1405,
                "sh": {
                    "year": 1405,
                    "month": 1,
                    "day": 1,
                    "month_name_fa": "فروردین",
                    "month_name_en": "Farvardin",
                    "weekday_fa": "شنبه",
                    "weekday_en": "Saturday"
                },
                "gregorian": {
                    "year": 2026,
                    "month": 3,
                    "day": 21,
                    "month_name_fa": "مارس",
                    "month_name_en": "March",
                    "weekday_fa": "شنبه",
                    "weekday_en": "Saturday"
                },
                "hijri": {
                    "year": 1447,
                    "month": 10,
                    "day": 1,
                    "month_name_fa": "شوال",
                    "month_name_en": "Shawwal",
                    "weekday_fa": "شنبه",
                    "weekday_en": "Saturday",
                    "estimate": false
                },
                "pahlavi": {
                    "year": 2585,
                    "month": 1,
                    "day": 1,
                    "month_name_fa": "فروردین",
                    "month_name_en": "Farvardin",
                    "weekday_fa": "شنبه",
                    "weekday_en": "Saturday"
                },
                "is_current_month": true,
                "is_prev_month": false,
                "is_next_month": false,
                "is_friday": false,
                "is_holiday": true,
                "events": [
                    {
                        "slug": "nowruz",
                        "title_fa": "نوروز - جشن آغاز سال نو",
                        "title_en": "Nowruz - New Year's Day",
                        "category": "national",
                        "is_holiday": true
                    }
                ]
            }
        ]
    ]
}

The response is shortened: calendar has six rows of seven cells; one cell is shown, with one of its occasions.

The moment of Nowruz GET /api/nowruz

The moment of the new year (the March equinox) from NASA's astronomical data, in any time zone.

ParameterStatusDescription
year_shrequiredThe new Persian year, e.g. 1406
tzrequiredTime zone (IANA)

Example:

https://www.persian-calendar.com/api/nowruz?year_sh=1406&tz=Europe/London
{
    "year_sh": 1406,
    "year_gregorian": 2027,
    "utc": "2027-03-20 20:24:41",
    "local": "2027-03-20T20:24:41+00:00",
    "timezone": "Europe/London",
    "countdown_seconds": 15194928,
    "local_parts": {
        "sh": {
            "year": 1405,
            "month": 12,
            "day": 29,
            "month_name_fa": "اسفند",
            "month_name_en": "Esfand",
            "weekday_fa": "شنبه",
            "weekday_en": "Saturday"
        },
        "weekday_fa": "شنبه",
        "weekday_en": "Saturday",
        "time": "20:24:41"
    }
}

The response is shortened: local_parts has the local date in all four calendars; only sh is shown here. A response may be cached for a minute, so count down from utc yourself.

Prayer times GET /api/prayer-times

A city's prayer times on a day, in local time, by the method of the Institute of Geophysics, University of Tehran.

ParameterStatusDescription
cityrequiredThe city's slug, from timezones
yearoptionalPersian year, with month and day; otherwise today in that city
monthoptionalPersian month
dayoptionalDay

Example:

https://www.persian-calendar.com/api/prayer-times?city=tehran&year=1405&month=1&day=1
{
    "city": "tehran",
    "timezone": "Asia/Tehran",
    "date_sh": "1405-01-01",
    "date_gregorian": "2026-03-21",
    "method": "Institute of Geophysics, University of Tehran (fajr 17.7°, maghrib 4.5°, midnight halfway from sunset to fajr)",
    "times": {
        "fajr": "04:43",
        "sunrise": "06:07",
        "dhuhr": "12:12",
        "sunset": "18:17",
        "maghrib": "18:35",
        "midnight": "23:30"
    }
}

Cities GET /api/timezones

Cities with their time zones and coordinates. The slug is the address of a city's pages: /prayer-times/{slug} and, for cities outside Iran, /nowruz/{slug}.

ParameterStatusDescription
country_codeoptionalTwo-letter country code, e.g. GB

Example:

https://www.persian-calendar.com/api/timezones?country_code=GB
{
    "data": [
        {
            "country_code": "GB",
            "country_name_fa": "بریتانیا",
            "country_name_en": "United Kingdom",
            "city_name": "لندن",
            "city_name_en": "London",
            "slug": "london",
            "timezone_id": "Europe/London",
            "latitude": 51.5085,
            "longitude": -0.1257
        }
    ]
}

The response is shortened: only the first city is shown.

Calendar files (iCalendar)

To add to Google Calendar, Apple Calendar or Outlook (the event names are in Persian):

  • https://www.persian-calendar.com/holidays.ics: this year's and next year's public holidays, to subscribe to; your calendar app keeps it up to date.
  • https://www.persian-calendar.com/holidays/1405.ics: one year's public holidays.
  • https://www.persian-calendar.com/nowruz/1406.ics: the moment of one year's Nowruz.

The widget and terms of use

To show today's date on your site without programming, use the today's date widget.

It is free to use, without guarantees; if you can, link to Persian-Calendar.com. Terms of use · admin@persian-calendar.com