Skip to content

DevDarsha-Admin/devdarsha-api-examples

BranchesTags

Repository files navigation

DevDarsha API — Code Examples

Official, copy-paste examples for the DevDarsha API platform, maintained by the DevDarsha team. Build applications with structured APIs for:

  • Panchang API — tithi, nakshatra, yoga, karana, festivals, muhurat, choghadiya, sunrise/sunset, monthly calendars, and yearly calendars.
  • Horoscope API — Rashifal, Janma Kundli, Vimshottari Dasha, D1/D9 charts, dosha analysis, matchmaking, natal interpretation, and full forecasts.
  • Numerology API — core numbers, date numbers, name analysis, personal cycles, Lo Shu, compatibility, name correction, structured reports, and bulk calculations.

All three products use the same API-key flow and the same success envelope: { "data", "meta", "dev_notes" }.

These examples are maintained integration references. Always rely on the live documentation and response metadata for the current API contract.

Quick start

All authenticated requests use:

X-Api-Key: YOUR_API_KEY
Content-Type: application/json

The canonical public host for all three API families is:

https://panchang.devdarsha.com

1. Panchang API

Get the Panchang for a date and supported city:

curl -X POST "https://panchang.devdarsha.com/v1/panchang/daily" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-04-15","city_id":"ujjain"}'

Useful response fields:

data.tithi[0].name
data.nakshatra[0].name
data.sun.rise
data.sun.set
data.festivals.data

2. Horoscope API

Generate a Janma Kundli from birth details:

curl -X POST "https://panchang.devdarsha.com/v1/horoscope/kundli" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date":"1990-08-15",
    "time":"10:30",
    "lat":22.5726,
    "lon":88.3639,
    "tz":"Asia/Kolkata"
  }'

Birth-based endpoints require date and time, plus either:

  • city or city_id, or
  • lat, lon, and an explicit IANA timezone such as Asia/Kolkata.

Timezone must not be guessed from bare coordinates.

3. Numerology API

Calculate a complete numerology profile using both supported systems:

curl -X POST "https://panchang.devdarsha.com/v1/numerology/core" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name":"Aarav Sharma",
    "date_of_birth":"1990-08-15",
    "systems":["chaldean","pythagorean"]
  }'

Numerology v1 accepts Latin or romanized name input. Use an explicit system or systems value where required.

Shared response envelope

Successful responses use the same top-level structure across products:

{
  "data": {
    // Product-specific calculated result
  },
  "meta": {
    "api_version": "v1",
    "service": "panchang | horoscope | numerology",
    "generated_at": "..."
  },
  "dev_notes": []
}

Error responses use:

{
  "error": "error_code",
  "message": "Human-readable explanation",
  "docs_url": "https://platform.devdarsha.com/..."
}

Product endpoint overview

Panchang API endpoints

Endpoint Minimum plan Purpose
POST /v1/panchang/daily Free Daily Panchang, festivals, muhurat, choghadiya, and solar/lunar data
POST /v1/panchang/monthly Amethyst+ Full month with daily Panchang records
POST /v1/panchang/yearly Sapphire+ Full year grouped into twelve months; quota cost is 12

Daily request body:

{
  "date": "2026-04-15",
  "city_id": "ujjain",
  "faith_filter": "hindu"
}

Supported faith_filter values:

all, hindu, islamic, sikh, buddhist, christian

Location rules:

  • city_id works on every plan.
  • lat + lon requires an eligible paid Panchang plan.
  • Supply timezone/tz when the selected route or coordinate mode requires it.

Horoscope API endpoints

Endpoint Method Minimum plan Purpose
/v1/horoscope/rashifal/:sign/:period GET Free Daily, weekly, or monthly sign-based Rashifal
/v1/horoscope/kundli POST Free Janma Kundli / D1 chart from birth details
/v1/horoscope/dasha POST Topaz+ Vimshottari Dasha timeline
/v1/horoscope/divisional/:varga POST Topaz+ D1 or D9 divisional chart
/v1/horoscope/doshas POST Topaz+ Manglik, Kaal Sarp, Sade Sati, and Pitra checks
/v1/horoscope/matching POST Topaz+ Ashtakoot / Gun Milan compatibility
/v1/horoscope/predict/natal POST Topaz+ Deterministic natal interpretation
/v1/horoscope/forecast/full POST Topaz+ Structured full forecast by life domain

Horoscope product page: https://platform.devdarsha.com/horoscope-api

Numerology API endpoints

Endpoint Method Minimum plan Purpose
/v1/numerology/core POST Free Complete core-number profile
/v1/numerology/date-numbers POST Free Moolank, Bhagyank/Life Path, attitude number, and Ank Jyotish
/v1/numerology/name POST Starter+ Expression, Soul Urge, Personality, and calculation evidence
/v1/numerology/cycles POST Starter+ Personal year, month, and day cycles
/v1/numerology/report POST Starter+ Structured multi-section numerology report
/v1/numerology/lo-shu POST Plus+ Lo Shu grid, present/missing numbers, and arrows
/v1/numerology/compatibility POST Pro+ Evidence-based compatibility between two profiles
/v1/numerology/name-correction POST Pro+ Deterministic name-number candidate analysis
/v1/numerology/bulk POST Scale Batch processing, up to the documented item limit

Numerology product page: https://platform.devdarsha.com/numerology-api

Panchang response example

The Panchang payload is returned under data:

{
  "data": {
    "date": "2026-04-15",
    "city": "Ujjain",
    "tithi": [
      {
        "number": 28,
        "name": "Trayodashi",
        "paksha": "Krishna"
      }
    ],
    "nakshatra": [
      {
        "number": 25,
        "name": "Purva Bhadrapada"
      }
    ],
    "sun": {
      "rise": "15-04-2026 06:06:30",
      "set": "15-04-2026 18:47:38"
    },
    "festivals": {
      "total": 2,
      "data": []
    }
  },
  "meta": {
    "version": "1.0",
    "computed_at": "...",
    "resolved_timezone": "Asia/Kolkata"
  },
  "dev_notes": []
}

A complete real-shape response is available at: panchang/examples/daily-panchang-response-sample.json.

Calculated values in stored snapshots can change as the engines are improved. Use the live response for current values.

Panchang monthly and yearly requests

Monthly

curl -X POST "https://panchang.devdarsha.com/v1/panchang/monthly" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-06","city_id":"ujjain"}'

Yearly

curl -X POST "https://panchang.devdarsha.com/v1/panchang/yearly" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"city_id":"ujjain"}'

The yearly route reports X-Quota-Cost: 12. A month that cannot be computed may contain an error entry and return X-Degraded: true.

Real-shape samples:

Coverage and quota headers

Panchang paid plans also use a coverage meter based on distinct (location, date) pairs. Exact allowances vary by plan and should not be hard-coded.

Successful Panchang responses may include:

Header Meaning
X-Coverage-Limit Monthly distinct location-date allowance
X-Coverage-Used Monthly coverage already consumed
X-Coverage-Remaining Monthly coverage still available
X-Coverage-Daily-Limit UTC-day coverage ceiling
X-Coverage-Daily-Used UTC-day coverage consumed
X-Coverage-Daily-Remaining UTC-day coverage remaining
X-Quota-Cost Units charged for the current operation

A 429 may represent either request-rate exhaustion or a product-specific coverage limit. Inspect the response error value before retrying.

Setup

Copy the example environment file and add your key:

cp .env.example .env
# Set DEVDARSHA_API_KEY in .env

Never commit a real API key.

The examples read environment variables but do not automatically load .env. Load it into Bash/Zsh with:

set -a
source .env
set +a

Or export variables directly:

export DEVDARSHA_API_KEY=your_api_key_here
export DEVDARSHA_CITY_ID=ujjain
export DEVDARSHA_DATE=2026-04-15

PowerShell:

$env:DEVDARSHA_API_KEY = "your_api_key_here"

Run the repository examples

The current runnable Node.js, Python, and PHP files in this repository are focused on Panchang. Horoscope and Numerology quick-start requests are included above; product-specific source examples can follow the same authenticated JSON request pattern.

Node.js 18+

node panchang/node/get-daily-panchang.js
node panchang/node/today-tithi.js
node panchang/node/festival-calendar-range.js 2026-04-01 2026-04-30
node panchang/node/get-monthly-panchang.js   # Amethyst+
node panchang/node/get-yearly-panchang.js    # Sapphire+

Python 3.9+

pip install -r panchang/python/requirements.txt
python panchang/python/get_daily_panchang.py
python panchang/python/get_monthly_panchang.py   # Amethyst+
python panchang/python/get_yearly_panchang.py    # Sapphire+

PHP 8.x

php panchang/php/panchang-client.php
php panchang/php/get-monthly-panchang.php   # Amethyst+
php panchang/php/get-yearly-panchang.php    # Sapphire+

The PHP examples also expose WordPress-compatible functions built on wp_remote_post().

Common errors

HTTP error Meaning Recommended action
400 missing_parameter A required field is absent Check the endpoint request schema
400 invalid_* A date, location, system, sign, period, or other value is malformed Validate the request against the relevant product docs
400 missing_location A location-dependent request lacks a valid city or coordinate set Supply city_id/city, or complete coordinates and timezone
400 unsupported_script Numerology name input uses an unsupported script Send Latin or romanized input for v1
401 missing_api_key X-Api-Key is absent Add the API-key header
401 invalid_api_key The key is invalid or inactive Replace it from the dashboard
402 upgrade_required A Numerology feature requires a higher plan Use an allowed endpoint or upgrade that product plan
403 plan_required The endpoint or input mode is outside the current plan Use the permitted route/input mode or upgrade
429 rate_limit_exceeded Request rate or quota exhausted Back off and inspect retry/quota headers
429 coverage_limit_exceeded Monthly Panchang coverage allowance exhausted Wait for reset or upgrade
429 coverage_daily_limit_exceeded Daily Panchang coverage ceiling reached Retry after the UTC-day reset
429 city_year_cap_exceeded Panchang city-year cap reached Change the request scope or upgrade
502 engine_parse_error Transient calculation-service response issue Retry with exponential backoff
503 engine_unavailable A calculation service is temporarily unavailable Retry shortly
503 coverage_enforcement_unavailable Coverage backend is temporarily unavailable Retry shortly
504 upstream_timeout The calculation service timed out Retry with exponential backoff

Do not retry validation, authentication, or plan errors without changing the request. Use short exponential backoff for transient 5xx responses.

Useful links

License

MIT — see LICENSE. Example code is free to use in your own projects.

About

Official code examples for DevDarsha Panchang, Horoscope and Numerology APIs. Build Vedic astrology and calendar integrations in minutes.

platform.devdarsha.com

Topics

nodejs python php rest-api jyotish indian-calendar horoscope-api astrology-api api-examples hindu-calendar vedic-astrology vedic-intelligence kundli numerology-api nakshatra panchang-api devdarsha

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages