# Indian Panchang & Vivah Muhurat API (`somurobo/indian-panchang-vivah-muhurat-api`) Actor

Indian panchang, tithi, nakshatra, choghadiya, published Lucknow vivah muhurat and 2027 festival dates from Somurobo's own public services.

- **URL**: https://apify.com/somurobo/indian-panchang-vivah-muhurat-api.md
- **Developed by:** [Somurobo](https://apify.com/somurobo) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 day panchangs

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Indian Panchang & Vivah Muhurat API

Panchang API, tithi nakshatra API, choghadiya API, muhurat API and Hindu calendar API using **Somurobo's own public Numerology services**. Get clean JSON for Indian calendar apps, wedding planners, dashboards and festival reminders. Hindi/English display options; no source website login, scraping proxy or API key required. The Apify platform may require an account/payment after the owner publishes this Actor.

**हिंदी:** पंचांग API, तिथि नक्षत्र API, चौघड़िया API, विवाह मुहूर्त API, हिंदू कैलेंडर API, त्योहार और व्रत की तारीख़ें। अपने app या शादी planning में Somurobo की website वाला डेटा इस्तेमाल करें।

This repository is prepared locally and **not published**. Owner publishing instructions: [docs/PUBLISH.md](docs/PUBLISH.md).

### What you get

| Mode | Input | Dataset result and coverage |
|---|---|---|
| `daily_panchang` | Inclusive dates, city or coordinates | One row per date: original tithi, nakshatra, yoga, karana, paksha, sunrise/sunset, muhurats and choghadiya. Dates in 2026–2027; up to 31 days per run. |
| `choghadiya` | Inclusive dates, city or coordinates | One row per date: eight day and eight night slots, start/end times and nature. Same date limits. |
| `vivah_muhurat` | Month/year, Lucknow | One row per month containing all published wedding dates, windows, nakshatra/tithi and auspicious lagna. November 2026–December 2027. Empty months are valid results. |
| `festival_dates` | Inclusive range within 2027, Delhi | One row per range with published **main festivals and vrat**. Not every ekadashi, eclipse or calendar observance; no city recalculation. |

Daily/choghadiya resolve Delhi, Mumbai, Bengaluru (Bangalore), Kolkata, Chennai, Hyderabad, Pune, Jaipur, Ahmedabad and Lucknow, including Hindi names. New Delhi is a Delhi alias. Other locations need explicit latitude/longitude; the city field then becomes a label. Supported coordinate box: latitude 6–38° N, longitude 68–98° E, intended for India; it is not a geographic border check. Coordinates override a recognised city name. No third-party geocoder is used.

Vivah timings are **Lucknow only**. Festival dates are the website's **New Delhi 2027** publication. These modes reject other coordinates/cities rather than silently relabel results. For festival requests, explicitly set `city: "Delhi"`; other modes default to Lucknow. Do not generalise location-specific wedding times to another city.

### Input examples

Daily panchang:

```json
{"mode":"daily_panchang","startDate":"2026-11-08","endDate":"2026-11-09","city":"Delhi","language":"hi"}
```

Coordinates and English:

```json
{"mode":"daily_panchang","startDate":"2026-11-08","endDate":"2026-11-08","city":"Mumbai custom","latitude":19.076,"longitude":72.8777,"language":"en"}
```

Other modes:

```json
{"mode":"choghadiya","startDate":"2026-11-08","endDate":"2026-11-08","city":"Jaipur","language":"en"}
```

```json
{"mode":"vivah_muhurat","month":11,"year":2026,"city":"Lucknow","language":"hi"}
```

```json
{"mode":"festival_dates","startDate":"2027-10-01","endDate":"2027-10-31","city":"Delhi","language":"en"}
```

Do not combine month/year with date range. Both coordinates must be supplied together. Invalid dates, unsupported ranges and unknown city names are rejected before website requests. See [input schema](.actor/input_schema.json) and [five sample files](examples).

### Output

The default Apify dataset is JSON; Console supports JSON/CSV downloads. Each success row contains `status`, `mode`, `language`, `city`, `timezone`, `sourceUrl`, `retrievedAt`, `data`, `sourceData`, `sourceLanguage` and `notice`. `data` applies a Hindi/English display glossary. `sourceData` preserves exact website fields (or exact parsed published table rows) for verification. Machine keys remain English; a glossary is not a full translation service, and unmapped prose can remain Hindi. It does not change dates, timings or predictions. Source language is predominantly Hindi, with some English labels.

API timestamps remain ISO UTC (`Z`); display in `Asia/Kolkata` / IST, UTC+05:30. Published vivah windows are exact website IST strings, including next-day markers. The Actor does not guess UTC conversions for those strings.

An error dataset row has `status: "error"`, `mode`, `task`, safe `code`, `message` and optional `httpStatus`; upstream response bodies are not exposed. `RUN_SUMMARY` in the default key-value store records successes, errors, unprocessed tasks and budget exhaustion. Website failures stop further date requests to protect the server. Partial successful rows remain available; a wholly failed source run exits as failed. Invalid input produces `RUN_SUMMARY` and a failed run without a result event charge.

### Proposed pay-per-event pricing — owner decides in Console

These are illustrative USD prices for this product, not configured billing. Apify platform costs and payout terms also apply.

| Console custom event ID (exact) | Charged unit | Proposed price |
|---|---|---|
| `day-panchang` | One successful daily panchang row | $0.002 ($2 per 1,000 days) |
| `day-choghadiya` | One successful date with day + night slots | $0.001 ($1 per 1,000 days) |
| `muhurat-month` | One successful published month, including a valid zero-date month | $0.02 |
| `festival-range` | One successful requested range of main festivals, including a valid empty range | $0.005 |

Code calls `Actor.pushData(result, eventId)` only after parsing succeeds, and stops when the SDK reports the event budget limit. Returned `chargedCount` is respected in the run summary. Errors use an uncharged dataset write; **do not enable a paid default dataset-item event** in Console. No custom charge for invalid requests, source errors or retry attempts. Local runs do not perform monetary charging. Cloud charging and payout have not been tested because no account/token or publication was used. Apify can have a platform Actor-start event/usage cost; review and disclose the final Console settings. [SDK charging documentation](https://docs.apify.com/sdk/js/docs/concepts/pay-per-event).

### Server protection

One request in flight per Actor run; request starts spaced at least six seconds apart (at most ten/minute/run). Maximum three attempts, 20-second request/body deadline and 4 MiB response limit. HTTP 429 waits at least 60 seconds and obeys a longer `Retry-After` (seconds or HTTP date). A wait over five minutes stops the run so it can be retried later without bypassing the source limit. Temporary failures use bounded backoff; other HTTP failures stop. Existing server rate limits remain authoritative; the public API did not advertise a fixed numerical quota in inspected response headers. No proxies, anti-bot bypass, internal traffic headers or credentials are sent.

**Before public release, set maximum concurrent Actor runs to 1 in Apify Console.** The per-run guard cannot coordinate unrelated cloud containers. Avoid parallel schedules and bulk tasks; increase throughput only after measuring source capacity. A festival/month page is fetched once per run. The allowlist contains only `/api/panchang`, `/vivah-muhurat` and `/hindi-calendar-2027` on `https://numerology.somurobo.online`; redirects and arbitrary URL inputs are forbidden.

Daily and choghadiya use the same endpoint/coordinates as the MCP integration. Vivah parses the same public page/month sections as MCP. Festivals additionally parse the existing public 2027 calendar; MCP itself exposes no festival-date tool. No website code, database, payment service or project configuration is modified.

### Accuracy and limitations

This Actor verifies **delivery parity with Somurobo website endpoints/published tables**, not religious or astronomical correctness. Five local `apify run` samples compare original data with independent public website requests; see [verification report](docs/verification.json) and saved sample results. The website's daily panchang UI can contain additional derived/display fields not supplied by `/api/panchang`; this Actor returns the public API's fields.

The [Somurobo panchang page](https://numerology.somurobo.online/panchang) states that 84 checks on 12 Lucknow dates were compared with Drik Panchang, all within three minutes with a maximum difference of one minute. That is the source website's historical claim; the underlying sample audit was not provided to this Actor. The [festival calendar](https://numerology.somurobo.online/hindi-calendar-2027) says its Delhi dates were compared with Drik Panchang. **No fresh independent Drik Panchang verification is claimed:** a direct sample request during this work returned HTTP 403. The Actor never calls Drik Panchang at runtime. Detailed status and a manual comparison checklist: [docs/ACCURACY.md](docs/ACCURACY.md).

Traditional observances vary by place, sunrise, local tradition and calculation convention. Wedding rows exclude personalised birth-chart suitability. **Not religious advice / यह धार्मिक सलाह नहीं है।** Confirm important rituals and wedding timings with a qualified local practitioner and local panchang. No guarantee is offered.

### Local development

Node.js 22+ required. Use the project-local CLI, without a global installation:

```bash
cd /opt/somurobo-apify
npm ci
export PATH="/opt/somurobo-apify/node_modules/.bin:$PATH"
export APIFY_CLI_DISABLE_TELEMETRY=1
npm run build
npm test
apify validate-schema
apify run --input-file examples/01-delhi-panchang.json
npm run verify
```

`npm run verify` sequentially runs all five examples through **apify-cli**, purging this project's default local storage between samples. It writes public calendar results/reports under `docs/`; do not use it on a dataset you need to retain. Local runs need no Apify account or token. Do not put secrets in input JSON. Cloud deployment and final monetization are owner actions described in [PUBLISH.md](docs/PUBLISH.md).

### Data handling and support

Requests contain only city labels, coordinates and calendar dates; no DOB, names, full chat, payment details or source credentials are needed. This Actor stores its input, dataset and run summary in Apify/local storage; Apify retention/access settings govern cloud copies and should be reviewed by the owner. Source website and Apify may process network metadata under their own policies. This repository ignores `.env` and storage; the Docker context excludes them. Source queries contain coordinates, so do not use a private home location if unnecessary. Support: **support@somurobo.online**. Source: https://numerology.somurobo.online/.

# Actor input Schema

## `mode` (type: `string`):

Choose one calendar product.

## `startDate` (type: `string`):

YYYY-MM-DD. Required except vivah. Example: 2026-11-08; festivals example: 2027-10-01.

## `endDate` (type: `string`):

YYYY-MM-DD. Max 31 days for daily/choghadiya. Festivals must stay within 2027. Omit for vivah.

## `city` (type: `string`):

Delhi, Mumbai, Bengaluru, Kolkata, Chennai, Hyderabad, Pune, Jaipur, Ahmedabad, Lucknow; Hindi names accepted. Other Indian locations require coordinates. Vivah: Lucknow only. Festivals: Delhi only.

## `latitude` (type: `number`):

Provide both coordinates to override city resolution. Supported Indian bounding box only (not a border/geographic guarantee). Example: 19.076.

## `longitude` (type: `number`):

Provide with latitude. Example: 72.8777.

## `language` (type: `string`):

Hindi or English display glossary; exact original is retained as sourceData. Unmapped website prose remains in source language.

## `month` (type: `integer`):

Only for vivah_muhurat: 1–12. Example: 11.

## `year` (type: `integer`):

Only for vivah_muhurat: 2026 or 2027. 2026 starts in November.

## Actor input object example

```json
{
  "mode": "daily_panchang",
  "startDate": "2026-11-08",
  "endDate": "2026-11-09",
  "city": "Delhi",
  "language": "hi"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "daily_panchang",
    "startDate": "2026-11-08",
    "endDate": "2026-11-09",
    "city": "Delhi"
};

// Run the Actor and wait for it to finish
const run = await client.actor("somurobo/indian-panchang-vivah-muhurat-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "daily_panchang",
    "startDate": "2026-11-08",
    "endDate": "2026-11-09",
    "city": "Delhi",
}

# Run the Actor and wait for it to finish
run = client.actor("somurobo/indian-panchang-vivah-muhurat-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "daily_panchang",
  "startDate": "2026-11-08",
  "endDate": "2026-11-09",
  "city": "Delhi"
}' |
apify call somurobo/indian-panchang-vivah-muhurat-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,somurobo/indian-panchang-vivah-muhurat-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/6pD65VzBon4kKhCjg/builds/8O76Zqjo3OJcEBMax/openapi.json