The Short Version
A Panchang API converts date and location inputs into developer-friendly JSON. In DevDarsha, protected calls go through the public gateway, which validates the API version, API key, plan, quota, timezone, and request logging before proxying the calculation to the internal engine.
The current public API uses URI versioning through /v1/.... The main Panchang endpoints are daily, monthly, and yearly responses, with plan gates controlling access to higher-volume or richer data.
This is a learning guide, not a replacement for the API reference. Use it to understand the moving parts, then use Documentation for exact request fields, errors, examples, and schemas.
What the Endpoints Do
Most integrations begin with POST /v1/panchang/daily. It is the simplest way to request the Panchang profile for a single date and supported location. Monthly and yearly endpoints are designed for calendar views, content planning, festival listings, and batch-like user experiences.
- Daily Panchang: suited for today screens, date detail pages, widgets, and live user lookups.
- Monthly Panchang: suited for calendar grids, upcoming observances, and editorial planning.
- Yearly Panchang: suited for annual calendars and heavier planning flows; yearly calls have a higher quota cost.
Authentication and Request Flow
Protected API calls use an API key. Keep it on your backend and send it with the request, commonly through the x-api-key header. Do not expose API keys in browser-only client code.
Once a request reaches DevDarsha, the gateway checks version support, authentication, plan eligibility, quota, rate limits, timezone handling, and logging rules. The engine stays internal; external clients call the gateway.
The gateway is where public API safety lives: versioning, auth, quota, response envelope behavior, request IDs, and plan filtering. The calculation engine is not meant to be exposed directly.
DevDarsha publishes a public Accuracy page that describes how each section of the API is verified, what calendar conventions are active, and how reported mismatches are handled. It is intended for developers who want to evaluate the data before committing to an integration.
Versioning and Stability
DevDarsha uses URI versioning. The launch version is v1, so public routes use paths such as /v1/demo/today and /v1/panchang/daily.
Deprecated versions are expected to receive notice before sunset except in critical security cases. Sunset versions return 410 Gone, and deprecated responses can include migration guidance in dev_notes.
Response Envelope
Website clients and API users should expect a consistent envelope with data, meta, and dev_notes. The data object contains the useful Panchang payload. The meta object explains how and when the response was produced.
meta.version: the API version used for the response.meta.computed_at: when the response was computed.meta.resolved_timezone: the IANA timezone resolved for the request.meta.data_sourceandmeta.cache_age_seconds: useful for debugging freshness and cache behavior.
Important response headers include X-Request-ID, X-Quota-Cost, X-Data-Source, and X-Cache-Age. Store the request ID when debugging a production issue.
Recommended Developer Flow
Start with the public demo endpoint or Playground to inspect a real response. Then move to the protected daily endpoint with your API key. Once the daily shape is clear, decide whether your product needs monthly, yearly, festival, muhurat, regional, or coordinate-based access.
Before launch, test representative cities, date ranges, plan gates, error responses, and quota behavior. Make sure your UI can handle optional or plan-filtered fields gracefully.