مستندات API تقویم

۰۱

شروع سریع

اولین درخواست را در کمتر از یک دقیقه ارسال کنید.

۱

حساب بسازیدثبت‌نام کنید و کلید API را از پنل بردارید.

۲

کلید را بفرستیدکلید را در Header هر درخواست قرار دهید.

۳

JSON دریافت کنیدپاسخ UTF-8 آماده استفاده در اپ یا وب‌سایت است.

cURL

curl "https://api.timestamp.ir/v1/events?date=1405-01-01" \
  -H "X-API-Key: YOUR_API_KEY"

۰۲

احراز هویت

تمام endpointها به کلید معتبر نیاز دارند.

روش پیشنهادی، ارسال کلید در Header اختصاصی زیر است. Bearer Token نیز پشتیبانی می‌شود.

HTTP Header

X-API-Key: ts_live_...

# Alternative
Authorization: Bearer ts_live_...

امنیت کلید

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

GET/v1/events

همه پلن‌ها

رویدادها و مناسبت‌ها

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

پارامتر	نوع	الزام	توضیح
`date`	string	اختیاری	تاریخ کامل شمسی با قالب `YYYY-MM-DD`
`miladi`	string	اختیاری	تاریخ کامل میلادی با قالب `YYYY-MM-DD`؛ باید به‌تنهایی ارسال شود
`year`	integer	برای سال	سال شمسی از ۱۳۰۰ تا ۱۵۰۰
`month`	integer	برای ماه	شماره ماه از ۱ تا ۱۲؛ حذف آن یعنی دریافت کل سال

یک روز شمسی · همه پلن‌ها/v1/events?date=1405-01-01

یک روز میلادی · همه پلن‌ها/v1/events?miladi=2026-10-24

یک ماه · همه پلن‌ها/v1/events?year=1405&month=1

یک سال · استاندارد و حرفه‌ای/v1/events?year=1405

cURL

curl "https://api.timestamp.ir/v1/events?miladi=2026-03-21" \
  -H "X-API-Key: YOUR_API_KEY"

JSON · 200 OK

{
  "success": true,
  "count": 1,
  "events": [{
    "id": "calendar_1",
    "title": "نوروز",
    "category": "solar",
    "is_holiday": true,
    "jalali_date": "1405-01-01",
    "gregorian_date": "2026-03-21",
    "lunar_date": "1447-10-02"
  }]
}

دسترسی سالانه

درخواست بدون month برای پلن استاندارد و حرفه‌ای فعال است. پلن رایگان پاسخ 403 plan_upgrade_required دریافت می‌کند.

GET/v1/holidays

همه پلن‌ها

تعطیلات رسمی

فقط رویدادهایی را برمی‌گرداند که تعطیل رسمی هستند. در این endpoint، ارسال هم‌زمان year و month الزامی است.

cURL

curl "https://api.timestamp.ir/v1/holidays?year=1405&month=1" \
  -H "X-API-Key: YOUR_API_KEY"

JSON · 200 OK

{
  "success": true,
  "count": 1,
  "events": [{
    "id": "calendar_1",
    "title": "نوروز",
    "category": "solar",
    "is_holiday": true,
    "jalali_date": "1405-01-01",
    "gregorian_date": "2026-03-21",
    "lunar_date": "1447-10-02"
  }]
}

GET/v1/today

استاندارد و حرفه‌ای

اطلاعات کامل امروز

یک پاسخ تجمیعی برای ساخت نمای «امروز»: تاریخ در سه تقویم، مناسبت‌ها، وضعیت روز کاری، تعطیلی بعدی، اوقات شرعی، طلوع و غروب و وضعیت ماه.

پارامتر	نوع	الزام	توضیح
`city`	string	الزامی	شناسه انگلیسی شهر؛ برای نمونه `tehran` یا `mashhad`

شهرهای پشتیبانی‌شده

تهران tehran تاکستان takestan قم qom ساری sari پرند parand دورود dorud رودسر rudsar مشهد mashhad اصفهان isfahan شیراز shiraz تبریز tabriz کرج karaj اهواز ahvaz رشت rasht زاهدان zahedan کرمان kerman یزد yazd اردبیل ardabil بندرعباس bandar-abbas اراک arak همدان hamedan قزوین qazvin زنجان zanjan سنندج sanandaj خرم‌آباد khorramabad گرگان gorgan سمنان semnan بوشهر bushehr کیش kish قشم qeshm چابهار chabahar نیشابور nishapur خمین khomein گلپایگان golpayegan گناباد gonabad گلبهار golbahar گرمسار garmsar آبادان abadan خرمشهر khorramshahr اسلامشهر eslamshahr دامغان damghan شاهین‌شهر shahin-shahr امیدیه omidiyeh داراب darab بهبهان behbahan رامسر ramsar سبزوار sabzevar سیرجان sirjan کاشمر kashmar گراش gerash شهربابک shahrbabak گنبد کاووس gonbad-kavus قیدار qeydar جهرم jahrom میاندوآب miandoab شهریار shahriar ارومیه urmia سلماس salmas دزفول dezful هشترود hashtrud قره‌آغاج qareh-aghaj تیکمه‌داش tikmeh-dash آذرشهر azarshahr بار bar فیروزه firuzeh شهر قدس shahr-e-qods ملارد malard فرون‌آباد faroonabad کمال‌شهر kamal-shahr محمدشهر mohammadshahr شیخ بیگلو sheykh-beyglu قره‌چمن qareh-chaman کرمانشاه kermanshah بجنورد bojnurd بیرجند birjand یاسوج yasuj شهرکرد shahrekord ایلام ilam کاشان kashan نجف‌آباد najafabad بندر انزلی bandar-anzali مراغه maragheh خوی khoy ساوه saveh بروجرد borujerd ملایر malayer نهاوند nahavand قمصر qamsar

cURL

curl "https://api.timestamp.ir/v1/today?city=tehran" \
  -H "X-API-Key: YOUR_API_KEY"

JSON · 200 OK

{
  "success": true,
  "date": {
    "jalali": "1405-06-24",
    "gregorian": "2026-09-15",
    "lunar": "1448-04-03",
    "weekday": "سه‌شنبه",
    "timezone": "Asia/Tehran"
  },
  "city": {
    "slug": "tehran",
    "name": "تهران",
    "province": "تهران"
  },
  "events": [],
  "holiday": {
    "is_holiday": false,
    "is_official_holiday": false,
    "is_weekend": false,
    "is_workday": true,
    "next_holiday": {
      "days_until": 3,
      "jalali_date": "1405-06-27",
      "gregorian_date": "2026-09-18",
      "weekday": "جمعه",
      "type": "weekend",
      "events": []
    }
  },
  "prayer_times": {
    "available": true,
    "updated_at": "2026-09-15 00:05:00",
    "timings": {
      "fajr": "04:26",
      "sunrise": "05:49",
      "dhuhr": "11:58",
      "sunset": "18:07",
      "maghrib": "18:25",
      "midnight": "23:18"
    }
  },
  "sun": {"available": true, "sunrise": "05:49", "sunset": "18:07"},
  "moon": {
    "available": true,
    "phase": "هلال افزاینده",
    "illumination": "13%"
  },
  "warnings": [],
  "generated_at": "2026-09-15T12:00:00+03:30"
}

GET/v1/meta

همه پلن‌ها

مشخصات سرویس و مصرف

پلن فعال، تاریخ انقضا، قابلیت‌ها، سقف مصرف و آمار ماه شمسی جاری را برای همان کلید برمی‌گرداند.

cURL

curl "https://api.timestamp.ir/v1/meta" \
  -H "X-API-Key: YOUR_API_KEY"

JSON · 200 OK

{
  "success": true,
  "version": "v1",
  "calendar": "jalali",
  "year_range": [1300, 1500],
  "plan": "standard",
  "plan_details": {
    "name": "استاندارد سالانه",
    "expires_at": "2027-09-15 12:00:00",
    "features": {"yearly_events": true, "today": true},
    "limits": {
      "requests_per_minute": 60,
      "requests_per_day": 3000
    }
  },
  "usage": {
    "current_minute": {"used": 1, "limit": 60, "remaining": 59},
    "today": {"used": 42, "limit": 3000, "remaining": 2958},
    "current_jalali_month": {
      "year": 1405,
      "month": 6,
      "total_requests": 320,
      "successful_requests": 316,
      "returned_records": 1840
    }
  },
	"endpoints": {
	  "events": "/v1/events?year={year}&month={month}",
	  "events_miladi": "/v1/events?miladi={YYYY-MM-DD}",
	  "events_year": "/v1/events?year={year}",
	  "holidays": "/v1/holidays?year={year}&month={month}",
	  "today": "/v1/today?city={city}",
	  "meta": "/v1/meta"
  },
  "generated_at": "2026-09-15T12:00:00+03:30"
}

۰۴

محدودیت مصرف

سهمیه‌ها برای هر کلید API محاسبه می‌شوند.

پلن	در دقیقه	در روز	روز کامل	دریافت سالانه
رایگان	۱۰	۲۰۰	ندارد	ندارد
استاندارد	۶۰	۳,۰۰۰	دارد	دارد
حرفه‌ای	۴۰۰	۵۰,۰۰۰	دارد	دارد

وضعیت سهمیه در Headerهای زیر همراه هر پاسخ ارسال می‌شود:

X-RateLimit-Limit-MinuteX-RateLimit-Remaining-Minute X-RateLimit-Limit-DayX-RateLimit-Remaining-Day

۰۵

خطاها

تمام خطاها ساختار JSON یکسانی دارند.

401invalid_api_keyکلید نامعتبر یا غیرفعال

403plan_upgrade_requiredنیاز به پلن بالاتر

405method_not_allowedمتد غیرمجاز

422invalid_parametersپارامتر نامعتبر

429rate_limit_exceededعبور از سهمیه

500internal_errorخطای پردازش

Error response

{
  "success": false,
  "error": "invalid_parameters",
  "message": "پارامتر month الزامی و باید بین 1 تا 12 باشد."
}

مستندات API تقویم ایران

شروع سریع

احراز هویت

رویدادها و مناسبت‌ها

تعطیلات رسمی

اطلاعات کامل امروز

مشخصات سرویس و مصرف

محدودیت مصرف

خطاها

اولین درخواست خود را ارسال کنید.