DevDarsha Numerology API — Code Examples

Copy-paste examples for the DevDarsha Numerology API: core numbers, date numbers, name analysis, personal cycles, Lo Shu grid, compatibility, name correction, structured reports, and batch processing. Deterministic — no LLM.

• Get a free API key: https://platform.devdarsha.com
• API documentation: https://platform.devdarsha.com/numerology-documentation
• Examples here: Node.js, Python, PHP (plain + WordPress), and the full OpenAPI spec.

One DevDarsha API key works across all three products (Panchang, Horoscope, Numerology), but paid access is scoped per product. Free endpoints still require a valid key.

---

Quick start (cURL)

curl -X POST "https://numerology.devdarsha.com/v1/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":["pythagorean","chaldean"]}'

The response is the standard envelope — the payload is under data:

{
  "data": { "results": { "pythagorean": { ... } }, "date_numbers": { ... }, "ank_jyotish": { ... } },
  "meta": { "api_version": "v1", "service": "numerology", "quota_cost_units": 2 },
  "dev_notes": []
}

A complete real-shape response is in examples/core-response-sample.json (and the include_calculations trace in examples/core-detailed-response-sample.json).

---

Auth & host

Host	https://numerology.devdarsha.com (clean paths). Legacy /v1/numerology/* works on every host.
Auth	X-Api-Key: <your key> header. The ?api_key= query param also works, but avoid it — URLs leak into logs and browser history.
Body	JSON (Content-Type: application/json) on every endpoint.

Systems: pass either system (string) or systems (array) — never both. Supported values are pythagorean and chaldean. Multiple systems cost one quota unit each (meta.quota_cost_units = systems.length).

Endpoints

Endpoint	Min plan	Payload path	Purpose
/v1/core	Free	data.results	Core profile from name + DOB
/v1/numerology/date-numbers	Free	data.date_numbers	Moolank, Bhagyank, Attitude (DOB only)
/v1/name	Starter+	data.systems	Name-only numbers
/v1/cycles	Starter+	flat data.personal_*_number	Personal year/month/day
/v1/report	Starter+	data.sections	Structured multi-section report
/v1/lo-shu	Plus+	data.lo_shu	Lo Shu grid, present/missing, arrows
/v1/compatibility	Pro+	data.compatibility	Two-profile compatibility
/v1/name-correction	Pro+	data.name_correction	Spelling-variant suggestions
/v1/bulk	Scale	data.results	Batch (up to 50 items)

Plans: free < starter < plus < pro < scale. A request below the endpoint minimum returns 403 plan_required with an upgrade_url.

date-numbers path: this endpoint is served ONLY on the legacy path /v1/numerology/date-numbers. The clean host does not expose /v1/date-numbers. The namespaced path works on every host. All examples use it.

/core vs /name: /core returns per-system numbers under data.results, while /name returns them under data.systems. This difference is intentional.

Numerology uses plain request metering (no coverage meter). The per-request quota cost is reported in meta.quota_cost_units.

---

Setup

Use the single root .env.example — copy it to .env and set your key:

cp .env.example .env          # from the repo root
set -a; source .env; set +a

Or export directly:

export DEVDARSHA_API_KEY=your_api_key_here
export DEVDARSHA_FULL_NAME="Aarav Sharma" DEVDARSHA_DOB=1990-08-15 DEVDARSHA_SYSTEM=pythagorean

Run the examples

Node.js (18+, no dependencies — native fetch):

node numerology/node/get-core.js
node numerology/node/get-date-numbers.js
node numerology/node/get-name.js            # Starter+
node numerology/node/get-cycles.js          # Starter+
node numerology/node/get-report.js          # Starter+
node numerology/node/get-lo-shu.js          # Plus+
node numerology/node/get-compatibility.js   # Pro+
node numerology/node/get-name-correction.js # Pro+
node numerology/node/get-bulk.js            # Scale

Python (3.9+):

pip install -r numerology/python/requirements.txt
python numerology/python/get_core.py
python numerology/python/get_date_numbers.py
# …get_name.py, get_cycles.py, get_report.py, get_lo_shu.py,
#   get_compatibility.py, get_name_correction.py, get_bulk.py

PHP (8.x, with cURL):

php numerology/php/numerology-client.php     # core (Free)
php numerology/php/get-date-numbers.php
# …get-name.php, get-cycles.php, get-report.php, get-lo-shu.php,
#   get-compatibility.php, get-name-correction.php, get-bulk.php

Each PHP file also exposes a *_wp() function built on wp_remote_post() for WordPress.

---

Sample responses

• examples/*-response-sample.json — successful (HTTP 200) responses.
• examples/*-plan-required-response-sample.json — the real 403 plan_required body (with upgrade_url) returned when a key is below a gated endpoint's minimum.

The /core samples are transcribed from the DevDarsha gateway's own machine-readable example. Other success samples are captured live — see the repository verification notes for which are pending a live capture. Values are illustrative; rely on the live response for current values.

---

Common errors

Every error is JSON: { "error", "message", "docs_url" } (plus upgrade_url on plan_required).

HTTP	error	Meaning
400	invalid_name / invalid_date_of_birth / invalid_system / missing_system	Bad input
400	invalid_target / invalid_cycle_date / invalid_section / bulk_too_large	Endpoint-specific input
400	unsupported_script	Name is not Latin/romanized (v1)
401	missing_api_key / invalid_api_key	Auth
402	upgrade_required	An explicitly requested report section is above the plan
403	plan_required	Plan below the endpoint minimum
429	rate_limited	Rate or quota exceeded
503	numerology_unavailable	Transient — retry with backoff

License

MIT — see ../LICENSE.