API Documentation

Integrate Iranian festival & occasion data into your apps — across Shamsi, Gregorian & Koroosh calendars.

Quick Start

01

Register or login with Google

02

Generate your API key from the dashboard

03

Attach the key via header or URL param

04

Hit any endpoint and go

Authentication

All API endpoints require authentication using your API key. You can provide it in two ways:

Method 1 — Header (recommended)

'/api/v1/occasions/today'
  -H 'X-API-Key: your-api-key-here'

Method 2 — URL query parameter

'/api/v1/occasions/today?apiKey=your-api-key-here'

Log in to see your real API key populated in all examples.

Rate Limits

Daily Limit: 1,000 requests

Rate limits are enforced per API key. Daily usage resets at midnight (00:00 UTC)

When you exceed the daily limit, you'll receive:

429 Too Many Requests - Daily rate limit exceeded (1000 requests/day)

💡 Tip: Monitor your usage in the dashboard to track your daily API calls

API Explorer

Get all occasions and festivals for today's date

/api/v1/occasions/today?lang=fa&gahanbar=false
  -H 'X-API-Key: your-api-key-here'
/api/v1/occasions/today?lang=fa&gahanbar=false&apiKey=your-api-key-here

Log in to see your real API key in the examples above.

API Endpoints

Shared optional parameters — available on every endpoint

lang

Response language. en for English, fa for Persian. Defaults to fa.

gahanbar

Include Gahanbar festivals in the results. true or false. Defaults to false.

GET/api/v1/occasions/today

Retrieve today's festivals and occasions based on the current date.

With header

/api/v1/occasions/today
  -H 'X-API-Key: your-api-key-here'

With URL param

/api/v1/occasions/today?apiKey=your-api-key-here
GET/api/v1/occasions

Fetch the full list of festivals and occasions from the database.

With header

/api/v1/occasions
  -H 'X-API-Key: your-api-key-here'

With URL param

/api/v1/occasions?apiKey=your-api-key-here
GET/api/v1/occasions/by-date

Look up festivals for a specific date, converting between Koroosh, Shamsi, and Gregorian calendars.

Parameters

calendarrequired

Calendar type: ko (Koroosh), sh (Shamsi), or gr (Gregorian)

daterequired

Date in YYYY-MM-DD format, e.g. 2025-08-01

With header

/api/v1/occasions/by-date?calendar=gr&date=2025-08-01
  -H 'X-API-Key: your-api-key-here'

With URL param

/api/v1/occasions/by-date?calendar=gr&date=2025-08-01&apiKey=your-api-key-here
GET/api/v1/occasions/by-day-and-month

Get festivals for a given day and month in the Shamsi calendar — useful when the year doesn't matter.

Parameters

dayrequired

Day of the month: 1–31

monthrequired

Shamsi month number: 1–12

With header

/api/v1/occasions/by-day-and-month?day=15&month=7
  -H 'X-API-Key: your-api-key-here'

With URL param

/api/v1/occasions/by-day-and-month?day=15&month=7&apiKey=your-api-key-here
GET/api/v1/occasions/month

List every festival in a specific Shamsi month. Omit the month param to default to the current month.

Parameters

monthoptional

Shamsi month: 1–12. Defaults to current month.

With header

/api/v1/occasions/month?month=7
  -H 'X-API-Key: your-api-key-here'

With URL param

/api/v1/occasions/month?month=7&apiKey=your-api-key-here
GET/api/v1/occasions/search

Search festivals by name and/or tag. At least one of name or tag is required.

Parameters

nameoptional

Festival name (case-insensitive partial match). At least name or tag is required.

tagoptional

Tag to filter by. At least name or tag is required.

With header

/api/v1/occasions/search?name=نوروز
  -H 'X-API-Key: your-api-key-here'

With URL param

/api/v1/occasions/search?name=نوروز&apiKey=your-api-key-here

Simple Integration

Get started in minutes with our REST API

Request

cURL
curl -X GET \
  'https://api.kooroshi.com/v1/occasions/today' \
  -H 'X-API-Key: your_api_key' \
  -H 'Accept-Language: fa'

Available Endpoints

/v1/occasions/today

Get today's occasions

/v1/occasions/date/:date

Get occasions for specific date

/v1/occasions/range

Get occasions in date range

Response

JSON
{
  logo_url: "https://res.cloudinary.com/daqtj4jyl/image/upload/v1771349856/IranianFestivalsApi/norooz_pckvdn.png",
  month: {
    name: "فروردین",
    number: 1,
    meaning: "پیش‌برنده، نیروی زندگی",
    root: "فروهر",
  },
  festival: {
    name: "نوروز",
    day: 1,
    origin_type: "ایرانی پیشازرتشتی",
    ritual_summary: "جشن آغاز سال نو، زایش طبیعت و نو شدن جهان",
    deity_or_concept: {
      name: "نظم کیهانی",
      meaning: "آغاز دوباره، هماهنگی جهان و زندگی",
    },
    festival_meaning: {
      pre_zoroaster: "آغاز بهار و چرخه طبیعی زندگی",
      post_zoroaster: "نو شدن جهان در چارچوب راستی و نظم",
    },
    audience_note: "جشنی کاملا طبیعی که بعدها معنا و تفسیر دینی گرفت",
    historical_confidence: "بالا",
    tags: ["سال نو", "بهار", "طبیعت"],
    date_type: "ثابت",
    date_type_explanation: "نوروز همیشه در روز ۱ فروردین برگزار می‌شود و تاریخ آن در تقویم رسمی شمسی تغییر نمی‌کند، هرچند لحظه تحویل سال نجومی است و زمان آن هر سال متغیر است.",
  },
}

Response Features

  • Persian and Gregorian dates
  • Zoroastrian calendar events
  • Rich metadata and tags

Error Codes

400Bad Request

Invalid or missing parameters.

401Unauthorized

API key is missing or invalid.

404Not Found

No matching calendar entry.

429Too Many Requests

Daily rate limit exceeded.

500Internal Server Error

Something went wrong on our end.

Need Help?

We're here to help you get up and running.

Contact Support