Persian Calendar Widget

Display Persian, Islamic, and Gregorian dates on your website

Features

✓Persian (Jalali), Islamic (Hijri), and Gregorian dates
✓Today's holidays and occasions
✓Light, dark, and auto theme support
✓Customizable locale, theme, and container
✓Lightweight — zero dependencies
✓Shadow DOM isolated — no CSS conflicts
✓Full RTL and LTR support

Developer API

Use the public Emrooz API for calendar catalogs, localized event tags, holiday feeds, and embeddable calendar widgets. Developer API keys unlock higher request limits and webhook management.

Base URL

https://api.emrooz.app/api/v1

Authentication model

✓Developer API keys use the `emz_` prefix. `POST /developer/register` returns the plain `api_key` once; store it securely because it cannot be retrieved later.
✓Pass developer keys with the `X-API-Key` header or the `api_key` query parameter. The key is required for `/developer/me`, `/developer/rotate-key`, and webhook management; it is optional on public calendar catalog and holiday feed endpoints.
✓Embed keys use the `emb_` prefix. `POST /embed/validate-key` validates a key and host, checks allowed domains, records a widget load, and enforces per-minute and monthly limits.
✓Free developer keys are limited to 60 requests per minute. The `calendar_data` plan is limited to 1000 requests per minute and is required for webhooks.

Create a developer API key

curl -X POST https://api.emrooz.app/api/v1/developer/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calendar Integration",
    "email": "[email protected]",
    "company": "Example Co",
    "website": "https://example.com"
  }'

Call a public catalog endpoint with a developer key

curl https://api.emrooz.app/api/v1/calendar/public-events?locale=en \
  -H "X-API-Key: emz_your_api_key_here"

Public endpoints

Method	Path	Description
POST	/developer/register	Create a developer API key. The response includes `api_key` once, plus the key prefix, plan, and rate limit.
GET	/developer/plans	List available developer plans, rate limits, and included features.
GET	/developer/me	Return the current developer key profile and active webhook subscriptions. Requires a developer API key.
POST	/developer/rotate-key	Rotate the current developer key and return the new `api_key` once. Requires a developer API key.
GET	/calendar/public-events/manifest	Return public calendar catalog metadata, including the current version and calendar offset data.
GET	/calendar/public-events/tags	Return localized public event tags. Supports the `locale` query parameter.
GET	/calendar/public-events	Return the published public event catalog. Supports `locale`, `country_code`, `region`, and `tag` filters.
GET	/feeds/holidays/{country}/{calendar}.ics	Return an iCalendar holiday feed. A developer key enables the combined `country=all` feed.
POST	/embed/validate-key	Validate an `emb_` widget key for a host and return plan, white-label, accent color, and remaining-load metadata.

Webhooks

The backend currently publishes one catalog-change webhook. Subscribe to it when your integration needs to refresh cached public calendar data after the catalog version changes.

Event name

calendar.version_bump

When it fires

It fires when the public calendar catalog version is bumped, including admin catalog changes, Islamic offset updates, and scheduled publication refreshes.

Create a webhook subscription

curl -X POST https://api.emrooz.app/api/v1/developer/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: emz_your_api_key_here" \
  -d '{
    "url": "https://example.com/webhooks/emrooz",
    "event": "calendar.version_bump"
  }'

Example delivery payload

{
  "event": "calendar.version_bump",
  "data": {
    "version": 42,
    "updated_at": "2026-06-12T15:30:00+00:00",
    "events_count": 384
  },
  "timestamp": "2026-06-12T15:30:01+00:00"
}

Webhook management endpoints

Method	Path	Description
POST	/developer/webhooks	Create a webhook subscription for `calendar.version_bump`. Requires the `calendar_data` developer plan. The response returns `secret` once.
DELETE	/developer/webhooks/{webhook}	Delete one webhook subscription owned by the current developer key.

Delivery and verification

✓Webhook requests include `event`, `data`, and `timestamp` in the JSON body, plus `X-Emrooz-Event` and `X-Emrooz-Signature` headers.
✓`X-Emrooz-Signature` is an HMAC-SHA256 signature of the JSON body using the webhook `secret` returned at creation time.
✓Delivery uses a 10-second HTTP timeout. Any non-2xx response or network exception increments `failure_count`; after 10 failures, the subscription is deactivated.
✓The dispatch job does not implement automatic retries for failed deliveries.

Quick Start

After you receive an API key, place this code anywhere in your HTML page:

Every external embed requires `data-key`. Free keys keep the Emrooz footer; Pro keys unlock white-label and server-managed accent color.

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here">
</script>

Customization

Customize the widget via `data-*` attributes and API key settings:

Attribute	Type	Default	Description
data-theme	"light" \| "dark" \| "auto"	"auto"	Widget color theme
data-locale	"fa" \| "en" \| "ar"	"fa"	Language and digit system
data-target	CSS selector	"#emrooz-widget"	Widget container selector
data-key	string	(required)	API key for monthly quota and paid features (white-label, custom accent)

Examples

Dark theme:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here"
  data-theme="dark">
</script>

English locale:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here"
  data-locale="en"
  data-theme="light">
</script>

Pro key:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_pro_key_here"
  data-theme="auto">
</script>
<!-- White-label + accent color are configured on the API key -->

Live Preview

The widget below is loaded live from emrooz.app:

Pricing

Free plan for personal sites and Pro plan for businesses

Free

$0/ per month

✓10,000 loads/month
✓Emrooz branding footer
✓Light, dark, auto themes
✓RTL/LTR support
✓Shadow DOM isolation

Pro

Recommended

$9/ per month

✓100,000 loads/month
✓White-label (remove branding)
✓Custom accent color
✓Priority support
✓All free features included

Get API Key

Usage with API key:

<div id="emrooz-widget"></div>
<script src="https://emrooz.app/embed.js"
  data-key="emb_your_api_key_here"
  data-theme="auto">
</script>