API تقویم ایرانی برای برنامه‌نویسان

شروع

• نشانی پایه: https://www.persian-calendar.com/api/
• همهٔ درخواست‌ها GET است و پاسخ JSON با کدگذاری UTF-8. کلید یا ثبت‌نام لازم نیست.
• هر سایتی می‌تواند از جاوااسکریپت مرورگر آن را صدا بزند (Access-Control-Allow-Origin: *).
• پاسخ موفق Cache-Control دارد؛ لطفاً پاسخ را تا همان مدت نگه دارید.
• درخواست نادرست پاسخ 422 می‌گیرد (و سال بی‌داده در nowruz پاسخ 404) با {"error": "…"}.
• برنامه‌ای که از سرور درخواست می‌فرستد بهتر است نام خود و نشانی سایت یا ایمیلش را در سرآیند User-Agent بفرستد، مثل MyApp/1.0 (https://example.com)، تا اگر مشکلی پیش آمد بتوانیم با شما تماس بگیریم.
• درخواست‌های هر سایت و برنامه شمرده می‌شود و استفاده‌ای که به کار سایت آسیب بزند ممکن است محدود شود. پاسخ 429 یعنی سهم روزانه تمام شده است و سرآیند Retry-After می‌گوید چند ثانیه تا روز بعد (به وقت تهران) مانده است؛ پاسخ 403 یعنی دسترسی بسته شده است. برای استفادهٔ زیاد به admin@persian-calendar.com بنویسید.
• تاریخ‌های قمری مطابق تقویم رسمی ایران است. تاریخ قمری آینده‌ای که هنوز رسماً اعلام نشده برآورد نجومی است و در پاسخ estimate: true دارد (روش محاسبه).

تاریخ امروز GET /api/today

امروز در چهار تقویم شمسی، میلادی، قمری و شاهنشاهی، با برج و سال حیوانی.

نمونه:

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"
    }
}

پاسخ کوتاه شده است: بقیهٔ پاسخ همان بخش‌های «تبدیل تاریخ» است: gregorian، hijri، pahlavi، zodiac و animal_year.

تبدیل تاریخ GET /api/convert

یک تاریخ از هر تقویم، در هر چهار تقویم.

نمونه:

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"
    }
}

تعطیلات رسمی سال GET /api/holidays

روزهای تعطیل رسمی یک سال شمسی، به ترتیب تاریخ؛ هر روز با مناسبت‌هایش (گاهی دو مناسبت در یک روز).

نمونه:

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
                }
            ]
        }
    ]
}

پاسخ کوتاه شده است: فقط نخستین روز از ۲۶ روز آمده است.

مناسبت‌های ماه یا روز GET /api/events

مناسبت‌های ملی، مذهبی، جهانی و فرهنگی یک ماه شمسی یا یک روز از آن.

نمونه:

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
        }
    ]
}

جدول ماه GET /api/calendar

جدول شش‌هفته‌ای یک ماه شمسی، هفته‌ها از شنبه، با تاریخ هر خانه در چهار تقویم و مناسبت‌هایش. خانه‌های پیش و پس از ماه روزهای ماه‌های کناری‌اند.

نمونه:

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
                    }
                ]
            }
        ]
    ]
}

پاسخ کوتاه شده است: calendar شش ردیف هفت‌خانه‌ای است؛ فقط یک خانه آمده و از مناسبت‌هایش یکی.

زمان تحویل سال GET /api/nowruz

لحظهٔ تحویل سال (اعتدال بهاری) از داده‌های نجومی ناسا، به وقت هر منطقهٔ زمانی.

نمونه:

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"
    }
}

پاسخ کوتاه شده است: local_parts تاریخ محلی را در هر چهار تقویم دارد؛ اینجا فقط sh آمده است. پاسخ تا یک دقیقه در حافظه می‌ماند، پس شمارش معکوس را خودتان از utc حساب کنید.

اوقات شرعی GET /api/prayer-times

اوقات شرعی یک شهر در یک روز، به وقت محلی و به روش مؤسسهٔ ژئوفیزیک دانشگاه تهران.

نمونه:

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"
    }
}

شهرها GET /api/timezones

شهرها با منطقهٔ زمانی و مختصاتشان. slug نشانی صفحه‌های شهر است: /prayer-times/{slug} و، برای شهرهای بیرون از ایران، /nowruz/{slug}.

نمونه:

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
        }
    ]
}

پاسخ کوتاه شده است: فقط نخستین شهر آمده است.

فایل‌های تقویم (iCalendar)

برای افزودن به Google Calendar، تقویم اپل یا Outlook:

• https://www.persian-calendar.com/holidays.ics: تعطیلات رسمی امسال و سال بعد، برای اشتراک؛ برنامهٔ تقویم خودش آن را به‌روز می‌کند.
• https://www.persian-calendar.com/holidays/1405.ics: تعطیلات رسمی یک سال.
• https://www.persian-calendar.com/nowruz/1406.ics: لحظهٔ تحویل یک سال.

ابزارک و شرایط استفاده

برای نشان دادن تاریخ امروز در سایت خود بدون برنامه‌نویسی، از ابزارک تاریخ امروز استفاده کنید.

استفاده رایگان است و بی‌تضمین؛ اگر می‌توانید به Persian-Calendar.com پیوند دهید. شرایط استفاده · admin@persian-calendar.com