API REFERENCE · 15 ENDPOINTS · LIVE · NO KEY REQUIRED

अनुप्रयोग-निर्देश-पुस्तकम्API Reference

The REST surface behind every chart, pañcāṅga and utsava on this site. No Astrodienst dependency, no Swiss Ephemeris fallback, no foreign authority in the numeric chain. Sun within ~0.1′ (p95), Moon within ~1′ of NASA/JPL Horizons. Fifteen endpoints, each with one named purpose — every example below runs today without a key.

Bharat Ephemeris v∞.4DOI 10.5281/zenodo.20024273 (v3 · 230 propositions · 83/83 machine-checked)internal catalog 890 · 805/805 · publication pendingcommercial doorway → /api

सत्य-परीक्षा · Accuracy

p95 / max vs JPL Horizons ≡ Swiss

Per-graha error vs JPL Horizons · arc-minutes · 1,000 samples · 2000–2050
Graha	p95 error	max error
सूर्य Sūrya · Sun	0.13′	0.21′
चन्द्र Candra · Moon	0.51′	1.0′
शुक्र Śukra · Venus	0.60′	1.5′
मङ्गल Maṅgala · Mars	0.91′	3.1′
शनि Śani · Saturn	1.0′	1.5′
गुरु Guru · Jupiter	1.2′	2.1′
बुध Budha · Mercury	2.2′	3.3′

Every graha stays within 3.3′ worst-case across fifty years. Tithi boundaries ~0.4 min · Moon-nakṣatra < 1 min. Raw residuals, method and the quarterly bake-off: /accuracy

अनुमति-स्तराः · Four licence tiers

agpl · commercial · institutional · enterprise

उन्मुक्तम्Unmuktam

Open Source

₹0 · forever · no royalty

Unlimited calls under AGPL-3.0

AGPL-compatible projects only

Self-hosted research, academic mirrors, AGPL apps

व्यापारिकम्Vyāpārikam

Commercial

Introductory · quoted per integration

Closed-source derivatives permitted

api@bharatephemeris.com

Proprietary SaaS, mobile apps, embedded products

संस्थागतम्Saṃsthāgatam

Institutional

Custom · scoped to enrolment

White-label · paramparā-config

Universities, observatories, research bodies

Classroom deployments, peer-reviewed studies

उद्यमम्Udyamam

Enterprise

Custom · annual · SLA scoped per contract

Full sovereign deployment + engineering line

Direct contract via api@

Banks, broadcasters, regulators, large platforms

AGPL-3.0 stays free forever for AGPL-compatible builds. The engine source remains sovereign-Bhāratīya across all four tiers.

आहूत-सूचि · Fifteen endpoints

tier-S compute · tier-W witness

POST/api/chartTier-SPublic

जातक-गणनम् Jātaka-gaṇanam

Full janma-kuṇḍalī computation. Returns the SovereignChart: 9 grahas, 12 bhāvas, 16 vargas, KP sub-lord ladder, Vimśottarī daśā tree, ṣaḍ-bala, jaimini-kāraka assignment.

Input: BirthChartInput {year, month, day, hour, minute, lat, lon, tzHours} — all required finite numbers (tzHours = numeric UTC offset, e.g. 5.5 for IST; year in [1900, 2100]). Optional: name (string), second (number). Errors: {ok:false, error:{code, message}} · HTTP 400. Anonymous calls are stateless; with a signed-in session cookie from this site the chart is ALSO saved to that user's own dashboard (RLS-gated to their account). Open · fair-use · no key.

curl -X POST https://bharatephemeris.com/api/chart -H 'Content-Type: application/json' \
  -d '{"name":"Sample","year":1990,"month":8,"day":15,"hour":4,"minute":32,"lat":28.61,"lon":77.21,"tzHours":5.5}'

POST/api/v1/bharat/chartTier-SPublic

सार्वभौम-गणनम् Sārvabhauma-gaṇanam

Versioned sovereign-substrate chart. Returns sāyana + nirayana longitudes for all 9 grahas, rāśi / nakṣatra / pāda per graha, lagna (ascendant), tithi, ahargana and a sovereigntySignature provenance note naming the exact śāstric kernels used.

Input: {birthDate "YYYY-MM-DD" (1900–2100), birthTime "HH:mm:ss", birthPlace {lat, lon, tz — IANA id, e.g. "Asia/Kolkata"}, ayanamsa: lahiri | raman | kp | surya-siddhanta | yukteshwar, nodeMode?: mean | true (default mean)}. Errors: {ok:false, error:{code, message, field?}} with stable codes (INVALID_FIELD, OUT_OF_EPOCH_RANGE, INVALID_TIMEZONE, …). Stateless · no persistence.

curl -X POST https://bharatephemeris.com/api/v1/bharat/chart -H 'Content-Type: application/json' \
  -d '{"birthDate":"1990-08-15","birthTime":"04:32:00", \
      "birthPlace":{"lat":28.61,"lon":77.21,"tz":"Asia/Kolkata"},"ayanamsa":"lahiri"}'

GET/api/panchangTier-SPublic

पञ्चाङ्गम् Pañcāṅgam

Live 5-limb pañcāṅga for the current instant: vāra · tithi · nakṣatra · yoga · karaṇa, plus Sun + Moon longitudes against Lahirī ayanāṃśa.

Accepts no query parameters (any query string returns 400) — historical pañcāṅga is out of scope. Use /api/utsavas for festival dates, /api/chart for any other moment.

curl https://bharatephemeris.com/api/panchang

GET/api/muhurtaTier-SRate-limited

मुहूर्त-गणनम् Muhūrta-gaṇanam

30 named muhūrtas + Abhijit, day/night choghaḍiyā (8 + 8 slots), 24 horā slots, Rāhu-kālam / Yamaganḍa / Gulika windows, and the day's pañcāṅga — for any date and place. Śāstra-table outputs (Muhūrta-Cintāmaṇi · Vasiṣṭha-Saṃhitā · BPHS Ch. 2).

Query (GET) or JSON body (POST — same fields): date "YYYY-MM-DD" (1900–2100), lat [-90, 90], lon [-180, 180], tz hours [-14, 14]. 60 req/hr/IP — the 429 body carries the ISO reset instant; X-RateLimit-Remaining / -Reset headers on every response.

curl 'https://bharatephemeris.com/api/muhurta?date=2026-06-12&lat=28.61&lon=77.21&tz=5.5'

GET/api/utsavasTier-SPublic

उत्सव-पञ्चाङ्गम् Utsava-pañcāṅgam

Vedic festival calendar for any year between 1900 and 2100. Deterministic — same inputs always return the same dates.

Required query: ?year=YYYY. Edge cache: 1 hour. Returns count + utsavas[] with date, tithi, nakṣatra, śāstra anchor.

curl 'https://bharatephemeris.com/api/utsavas?year=2026'

POST/api/rectifyTier-SPublic

जन्म-काल-शुद्धिः Janma-kāla-śuddhiḥ

Birth-time rectification by reverse-fit. Submit a time window and a list of dated past events, receive the top 3-5 candidate birth moments ranked by Vimśottarī daśā / antara / pratyantara congruence.

Input: {birthDate "YYYY-MM-DD", birthWindow {startTime, endTime} as "HH:MM" (end strictly after start), location {lat, lon, tz hours}, events [{date "YYYY-MM-DD", category}], gridMinutes? [1, 60]}. Categories: marriage · career-shift · relocation · child-birth · parent-death · spouse-death · major-illness · education-milestone · windfall. Reverse-fit only — never issues a future prediction. No persistence.

curl -X POST https://bharatephemeris.com/api/rectify -H 'Content-Type: application/json' \
  -d '{"birthDate":"1985-03-12","birthWindow":{"startTime":"10:00","endTime":"12:00"}, \
      "location":{"lat":19.07,"lon":72.88,"tz":5.5},"events":[{"date":"2012-06-04","category":"marriage"}]}'

POST/api/sahajaTier-WRate-limited

सहज-प्रज्ञा Sahaja-prajñā

Multi-turn śāstric counsel. The model may call /api/chart, /api/panchang, /api/utsavas as tools mid-turn; never issues predictions; every reply is post-classified for prediction-slip and carries the structural-counsel disclaimer.

Accepts either legacy {message, history?} or modern {messages: [{role,content}, …]}. 10 req/hr/IP via a durable cross-instance sliding window (5/hr conservative single-instance fallback); X-RateLimit-Limit / -Remaining / -Reset headers on 429. DEMO mode (no model key configured) returns canned guidance — useful for local dev.

curl -X POST https://bharatephemeris.com/api/sahaja -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Explain Saturn through the 7th in Kanyā lagna."}]}'

POST/api/operator/dispatchTier-SRate-limited

कर्तृ-निक्षेपणम् Kartṛ-nikṣepaṇam

Operator dispatch surface — α-gate · mukha selection · bridge probe · handler · handshake. Returns the full OperatorResponse envelope so external systems can inspect framework behaviour.

Open · 30 req/hr/IP via in-memory bucket. No predictions, no stored user data, no external calls by default.

curl -X POST https://bharatephemeris.com/api/operator/dispatch -H 'Content-Type: application/json' \
  -d '{"mukha":"east","intent":"probe","payload":{}}'

GET/api/operator/dispatchTier-SPublic

कर्तृ-स्थितिः Kartṛ-sthitiḥ

Operator handshake status. Read-only echo of α-time, current mukha, bridge availability — useful for liveness probes.

No side effects · no rate limit.

curl https://bharatephemeris.com/api/operator/dispatch

GET/api/pressTier-WPublic

पत्रकार-कोशः Patrakāra-kośaḥ

Machine-readable PRESS_FACTS — every fact, number, DOI, quote, founder bio, asset URL in one stable JSON object. Useful for newsrooms, citation tools, and CMS sync.

Edge cache: 6 hours · CORS: open to '*' · revalidates on redeploy.

curl https://bharatephemeris.com/api/press

GET/api/rssTier-WPublic

वार्तिक-सूचिः Vārtika-sūciḥ

Meta-feed listing every Bharat Ephemeris RSS surface. Aggregators subscribe here and auto-discover child feeds.

curl https://bharatephemeris.com/api/rss

GET/api/rss/dailyTier-WPublic

दिन-पञ्चाङ्ग-वार्तिकम् Dina-pañcāṅga-vārtikam

Daily pañcāṅga feed — one item per day with vāra · tithi · nakṣatra · yoga · karaṇa and the day's principal utsava if any.

curl https://bharatephemeris.com/api/rss/daily

POST/api/indexnowTier-WPublic

तत्क्षण-सूचनम् Tatkṣaṇa-sūcanam

IndexNow ping proxy. Notifies Bing + Yandex (and partners) the instant new content publishes, instead of waiting for the next crawl pass.

Accepts {urlList: string[]} POST body, or pings the homepage + top 10 routes on bare GET.

curl -X POST https://bharatephemeris.com/api/indexnow -H 'Content-Type: application/json' \
  -d '{"urlList":["https://bharatephemeris.com/substrate","https://bharatephemeris.com/accuracy"]}'

GET/api/indexnowTier-WPublic

तत्क्षण-सूचन-दर्शनम् Tatkṣaṇa-sūcana-darśanam

IndexNow homepage helper — pings the apex + top 10 routes with one call. Used by the daily build pipeline.

curl https://bharatephemeris.com/api/indexnow

GET/api/healthTier-WPublic

स्वास्थ्य-दर्शनम् Svāsthya-darśanam

Liveness + dependency-presence probe — {status, time, checks} with presence booleans only, never secret values. Always HTTP 200 so uptime monitors read the JSON body. This is the public uptime-honesty surface: no SLA is claimed on the open tier; probe it yourself.

No params · no rate limit · cache-control: no-store.

curl https://bharatephemeris.com/api/health

प्रमाणीकरणम् · Authentication · rate limits

per-ip hourly buckets

There are no API keys today — every endpoint is public. Commercial keys (raised ceilings, closed-source licensing) are issued by request: api@bharatephemeris.com. CORS is opened to * on /api/press, /api/rss and the RSS children so external newsrooms and aggregators can fetch directly.

Three routes enforce a per-IP hourly bucket (limits read from the route source, not aspirational): POST /api/sahaja — 10 requests/hour (durable cross-instance sliding window; 5/hour conservative single-instance fallback). GET/POST /api/muhurta — 60 requests/hour. /api/operator/dispatch — 30 requests/hour on POST. Everything else — chart, v1 chart, pañcāṅga, utsavas, rectify, health, press, rss, indexnow — is open fair-use with no enforced bucket.

A 429 carries X-RateLimit-Remaining / X-RateLimit-Reset headers (sahaja adds X-RateLimit-Limit) and an ISO reset instant in the body — there is no Retry-After header today. Back off until the reset, then replay — the bucket refills on the wall clock, not on the request stream.

Uptime honesty: no SLA is claimed on the open tier. Liveness is publicly probeable at GET /api/health; contractual SLA terms are scoped per Enterprise agreement. Accuracy ground truth lives at /accuracy.

त्रुटि-संविदा · Error envelope

structured · idempotent retries safe

HTTP semantics are preserved — no 200 wrappers around failures. Two envelope families are in use: the chart endpoints return a structured { ok: false, error: { code, message, field? } } object with stable machine-matchable codes; the compute + feed endpoints return a flat { error: "kebab-case-code", message | details } object. Idempotent retries are safe on every GET route and on POST /api/chart, POST /api/v1/bharat/chart + POST /api/rectify (same input always yields the same output).

// chart · v1 chart
{ "ok": false, "error": { "code": "INVALID_FIELD", "message": "…", "field": "birthDate" } }

// panchang · utsavas · muhurta · operator · sahaja
{ "error": "rate-limit-exceeded", "details": "Try again after 2026-06-12T09:00:00.000Z." }

Four codes · as emitted by the live handlers
Code	Title	Cause · remedy
400	Bad input	Required field missing or out of range. The message names the offending field (and the v1 endpoint returns a stable error.code + field key) — fix, retry.
429	Quota exceeded	Per-IP hourly bucket consumed (sahaja 10/hr · muhurta 60/hr · operator 30/hr). X-RateLimit-Remaining / -Reset headers + an ISO reset instant in the body — back off until the reset, then replay.
500	Substrate fault	Engine fault during computation. Chart endpoints degrade per-body where possible (failed values become NaN with a note in sovereigntySignature) instead of collapsing the whole chart.
503	Counsel offline	/api/sahaja only — the paid model path fails closed when no durable cross-instance rate limiter is configured. Pure-compute endpoints are unaffected.

साक्षात्-तुलना · Ground truth

jpl horizons · zenodo · agpl

Every numeric output is reproducible against JPL Horizons over a 200-year window. The quarterly bake-off (1,000 dates × 9 grahas) lives at /accuracy with raw residuals, p50, p95 and per-graha Tier-S/Tier-W verdicts. The open lunar improvement track is published at /research.

The algebraic substrate is deposited at Zenodo DOI 10.5281/zenodo.20024273 — v3 of the record: 230 propositions, 83/83 machine-checked. The current internal catalog (890 propositions · 805/805 machine-checked — APEX v5/v6) is publication-pending and not yet covered by that DOI. Every claim wears a Tier-S algebraic tag (i)–(ix) or a Tier-W witness tag. Reproducible proof scripts ship in the Zenodo deposit (DOI 10.5281/zenodo.20024273) under CC BY 4.0.

अनुमति-पथौ · Two licence paths

agpl · commercial

उन्मुक्तम्AGPL — open-source

Run the engine inside any AGPL-3.0 compatible project. Your derivative source remains open and AGPL-licenced. Free forever, no royalty, no per-call meter. Research mirrors, peer-review reproductions, academic syllabi, AGPL applications.

व्यापारिकम्Commercial — closed-source

Ship the engine inside a proprietary product without opening your derivative. Introductory pricing — annual fee scaled to active user-count, quoted per integration. Write to api@bharatephemeris.com with platform name, user-count band and integration surface.

enterprise · white-label

Institutional and Enterprise tiers ship as white-label deployments — paramparā-config, sovereign infrastructure, direct engineering line, scoped SLA. Universities, observatories, banks, broadcasters, regulators.

सहयोग · View partnerships →

(R, g, k) = (ℤ/3³³⁷ℤ, 2, k=337) · published: DOI 10.5281/zenodo.20024273 (v3 · 230 propositions · 83/83) · internal: 890 · 805/805 · publication pending

अनुप्रयोग-निर्देश-पुस्तकम् · API Reference