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

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

X-API-Key: ts_live_...

رویدادها

با یک تاریخ یا ماه شمسی درخواست بفرستید. برای دریافت ماهانه، هر دو پارامتر year و month الزامی هستند.

GET https://api.timestamp.ir/v1/events?date=1405-01-01
GET https://api.timestamp.ir/v1/events?year=1405&month=1

تعطیلات

GET https://api.timestamp.ir/v1/holidays?year=1405&month=1

مشخصات سرویس

GET https://api.timestamp.ir/v1/meta

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

{
  "plan": "pro",
  "plan_details": {
    "name": "حرفه‌ای سالانه",
    "expires_at": "2027-09-06 12:00:00",
    "limits": {
      "requests_per_minute": 400,
      "requests_per_day": 50000
    }
  },
  "usage": {
    "current_minute": {"used": 3, "limit": 400, "remaining": 397},
    "today": {"used": 125, "limit": 50000, "remaining": 49875},
    "current_jalali_month": {
      "year": 1405,
      "month": 6,
      "total_requests": 1820,
      "successful_requests": 1798,
      "returned_records": 9400
    }
  }
}

ساختار پاسخ

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

محدودیت مصرف

پلن رایگان: ۱۰ درخواست در دقیقه و ۲۰۰ درخواست در روز. پلن حرفه‌ای: ۴۰۰ درخواست در دقیقه و ۵۰,۰۰۰ درخواست در روز. مقدار باقی‌مانده در Headerهای X-RateLimit-Remaining-Minute و X-RateLimit-Remaining-Day برمی‌گردد؛ عبور از سقف پاسخ ۴۲۹ می‌دهد.

خطاها

خطاها دارای success=false، کد error و متن message هستند. کدهای رایج: ۴۰۱ کلید نامعتبر، ۴۲۲ پارامتر نامعتبر، ۴۲۹ عبور از سقف و ۵۰۰ خطای داخلی.