Developer guide

When to use this service

Use Persian Calendar for explicit Gregorian–Persian civil-date conversion, today’s Persian date in a named timezone, and exact Persian month lengths and boundaries. The endpoints are public, read-only and do not require an account or API key.

Ask which input calendar and date format the user means. An ambiguous date such as 03/04/2026 is not an accepted API format. Use ASCII YYYY-MM-DD; the website’s interactive converter also accepts Persian and Arabic numerals.

Method and supported input

The website, API and agent tools use the same jalaali-js calculation engine. Public input years are 1800–2200 for Gregorian dates and 1280–1600 for Persian dates. Limits apply to the input calendar; the converted output can fall outside the other input range. The interactive website retains its broader historical range.

Impossible dates return HTTP 400 with an error string. For example, 2026-02-31 and Persian 1405-12-30 are rejected. Never silently normalize invalid input. Date-only conversion does not shift a date between timezones.

These are civil-calendar calculations. They do not calculate the astronomical instant of the equinox or solstice. The celebration guides record cultural calendar conventions and are not a statutory public-holiday service.

Today, timezones and freshness

Supply timeZone as a valid IANA name, such as Asia/Tehran, Europe/London or UTC. The response reports the resolved timeZone and the calculation timestamp. An invalid timezone returns HTTP 400. Without this parameter, /api/today preserves its existing server-timezone behavior; it does not infer the visitor’s location.

Live API and MCP responses use Cache-Control: no-store. Recalculate “today” when its timezone crosses midnight. The isHoliday field is retained for compatibility: it marks a Friday or a date in the site’s cultural collection, not verified legal holiday status.

MCP and browser tools

Connect a compatible remote MCP client to https://persiancalendar.online/mcp using Streamable HTTP. The stateless endpoint supports the 2026-07-28 protocol and legacy stateless clients through the official MCP TypeScript SDK. Authentication is not required. Available tools: convert_date, get_today, get_persian_month.

The same three read-only tools are registered through WebMCP when the browser exposes a supported modelContext API. Other browsers continue using the ordinary website. WebMCP availability depends on the browser and agent; remote MCP does not require an open website tab.

Tool results include a source URL tied to the requested date, year or timezone. Cite that URL with the returned context. Documentation describes supported operations; publishing it does not guarantee that an assistant will discover, recommend or cite the website.

Access and response handling

Server-to-server callers can request the public HTTPS endpoints directly. Browser CORS permissions retain the site’s existing origin restrictions. There are no credentialed operations. Handle HTTP 400 errors instead of presenting their contents as a successful conversion.

The month endpoint takes a Persian year and a month number from 1 to 12. It returns the exact Gregorian start/end dates, actual day count, leap-year flag and a firstWeekdayIndex with Saturday = 0 through Friday = 6.

Try a request

GET https://persiancalendar.online/api/convert?from=gregorian&date=2027-03-21

GET https://persiancalendar.online/api/convert?from=persian&date=1406-01-01

GET https://persiancalendar.online/api/today?timeZone=Asia%2FTehran

GET https://persiancalendar.online/api/month?year=1403&month=12

Tool names

• convert_date: Convert an explicit Gregorian or Persian civil date. Reject impossible dates. Date-only conversion does not use a timezone. Returns both calendar components and a link to the converter.
• get_today: Get the current Gregorian and Persian civil date in an explicit IANA timezone. Ask for a timezone when the user's location is unknown. The legacy isHoliday flag is not proof of a statutory holiday.
• get_persian_month: Get the actual length, leap-year flag and Gregorian first/last civil dates of one Persian month. The firstWeekdayIndex is zero-based with Saturday = 0.

The remote MCP URL is https://persiancalendar.online/mcp. Use a client that supports Streamable HTTP. Its server card and AI catalog describe the working service.

For agents that support installable skills, the skill index publishes one focused Persian calendar skill with a SHA-256 integrity digest.