Persian date conversion API

A free JSON API to convert dates between the Persian (Jalali, Shamsi, Solar Hijri) and the Gregorian calendar. No API key, CORS enabled for all origins, responses include month names in Persian, German and English plus the day of the week.

Endpoints

• GET /api/v1/convert?from=jalali&date=1405-08-05 – Persian → Gregorian
• GET /api/v1/convert?from=gregorian&date=2026-10-27 – Gregorian → Persian
• GET /api/v1/today – today in both calendars (optional tz, IANA time zone, default Asia/Tehran)
• OpenAPI 3 specification (JSON)

Example with curl

curl "https://shamsimiladi.com/api/v1/convert?from=jalali&date=1405-08-05"

{
  "input": {
    "from": "jalali",
    "date": "1405-08-05"
  },
  "jalali": {
    "date": "1405-08-05",
    "year": 1405,
    "month": 8,
    "day": 5,
    "monthName": {
      "fa": "آبان",
      "de": "Aban",
      "en": "Aban"
    },
    "isLeapYear": false
  },
  "gregorian": {
    "date": "2026-10-27",
    "year": 2026,
    "month": 10,
    "day": 27,
    "monthName": {
      "fa": "اکتبر",
      "de": "Oktober",
      "en": "October"
    }
  },
  "weekday": {
    "index": 2,
    "fa": "سه‌شنبه",
    "de": "Dienstag",
    "en": "Tuesday"
  }
}

Example with JavaScript

const res = await fetch('https://shamsimiladi.com/api/v1/today?tz=Europe/Berlin');
const data = await res.json();
console.log(data.jalali.date, data.jalali.monthName.en);

Errors

Invalid input returns HTTP 400 with a JSON body like {"error": {"code": "invalid_date", "message": "..."}}. Possible codes: invalid_from, invalid_format, invalid_date, out_of_range, invalid_timezone. Dates must use the format YYYY-MM-DD; Persian years 1–3177 and Gregorian years 622–3798 are supported.

Limits and caching

Each IP may send 60 requests per minute (short bursts are tolerated); above that the API answers with HTTP 429. Conversion results never change and are cacheable for a day, /today for one minute.

Terms of use

The API is free for personal and commercial use. There is no uptime guarantee. If you use it in a public website or app, please credit shamsimiladi.com with a visible link – that is all we ask. Please cache results instead of sending the same request repeatedly.

Prefer a ready-made display? Use the embeddable widget.

Back to the date converter