DiAstrologer — Developer Guide¶

Pure Parashari Vedic Astrology API. All calculations run on the Vedic Ephemeris with Lahiri ayanamsa and Whole-Sign houses. 399 public endpoints across 51 domains.

• Base URL (local): http://127.0.0.1:8000
• Base URL (production): https://api.example.com
• Interactive docs: /docs (Swagger) · /redoc
• API Reference: ../reference/README.md
• Internal endpoints: ../internal/README.md (not public)

1. Two API surfaces¶

Platform API (/api/v1)¶

Register a user (POST /api/v1/auth/register), log in (POST /api/v1/auth/login) to receive JWT access_token / refresh_token, and send Authorization: Bearer <access_token> on every call.

Developer API (/api/dev/v1)¶

The monetized API. Flow:

1. POST /api/dev/v1/request-access — request a developer account.
2. An admin approves it (/api/dev/v1/admin/access-requests).
3. GET/POST /api/dev/v1/keys — list or create an API key (CreateKeyBody { name }).
4. Call tools with header X-API-Key: <api_key>.

Every developer gets 100 free credits (≈6 calls at ₹15 each). After that each tool call costs 15 credits (₹15) flat — see the pricing table in section 6.

2. Quickstart¶

2.1 Register & login (Platform API)¶

# 1. Register
curl -X POST http://127.0.0.1:8000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","username":"dev","password":"secret123","full_name":"Dev"}' \
  -H 'X-Admin-Key: ...'

# 2. Login
curl -X POST http://127.0.0.1:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"secret123"}'
# → {"access_token":"...","refresh_token":"...","expires_in":...}

2.2 First chart calculation¶

curl -X POST http://127.0.0.1:8000/api/v1/chart/birth \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Rahul Sharma",
    "date": "1990-06-15",
    "time": "14:30:00",
    "latitude": 28.6139,
    "longitude": 77.209,
    "timezone": "Asia/Kolkata",
    "place_name": "Delhi"
  }'

2.3 First developer API call¶

curl -X POST http://127.0.0.1:8000/api/dev/v1/vedic/chart/birth \
  -H 'X-API-Key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{"date":"1990-06-15","time":"14:30:00","latitude":28.6139,"longitude":77.209,"timezone":"Asia/Kolkata"}'

Check remaining credits at any time:

curl -X GET http://127.0.0.1:8000/api/dev/v1/credits -H 'X-API-Key: <api_key>'

3. Authentication¶

Platform API (JWT)¶

• POST /api/v1/auth/register — create account.
• POST /api/v1/auth/login — returns { access_token, refresh_token, expires_in }.
• POST /api/v1/auth/refresh — exchange a refresh token for a new access token.
• GET /api/v1/auth/me — current user (requires bearer).
• POST /api/v1/auth/logout — revoke the current token.
• POST /api/v1/auth/change-password, /forgot-password, /reset-password.

Send: Authorization: Bearer <access_token>.

Developer API (API keys)¶

• Header X-API-Key: <api_key>.
• Keys are created via GET/POST /api/dev/v1/keys and deleted via DELETE /api/dev/v1/keys/{key_id}.
• Missing/invalid key → 401 {"detail": "API key required. Send it in the X-API-Key header."}.

4. Core concepts¶

Birth data (the universal request shape)¶

Almost every calculation endpoint accepts the same birth-data fields:

If timezone is omitted the server estimates it from longitude (38 offset buckets). For exact D60/karma analysis always supply a real IANA timezone.

Astrological constants¶

• Ayanamsa: Lahiri (Chitrapaksha).
• House system: Whole Sign (classical). Planets never shift houses; strength varies by Bhava Intensity (Bhava Madhya → full result, Bhava Sandhi → weak result).
• Grahas: Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu.
• Divisional charts (Vargas): D1, D2, D3, D4, D7, D9, D10, D12, D16, D20, D24, D27, D30, D40, D45, D60 — all available under /api/v1/varga/*.

Response envelope¶

Most endpoints return:

{
  "success": true,
  "data": { "...": "payload" },
  "metadata": { "computed_ms": 123, "rule_matches": 42 }
}

A few return raw objects. Check each endpoint's reference page for the exact shape.

5. Error handling¶

Validation example:

{
  "detail": [
    {
      "loc": ["body", "date"],
      "msg": "Input should be a valid date in the format YYYY-MM-DD",
      "type": "date_from_datetime_parsing"
    }
  ]
}

6. Credits & pricing (Developer API)¶

Source: GET /api/dev/v1/pricing

• Unit: 1 credit = ₹1
• Free allowance: 100 credits per developer
• Price after free calls: 15 credits (₹15) per call, flat, across all tools

Order more: POST /api/dev/v1/credits/order → Razorpay → POST /api/dev/v1/credits/verify.

7. Domain map (what to call for what)¶

8. Code examples¶

Python¶

import requests

BASE = "http://127.0.0.1:8000"
birth = {
    "date": "1990-06-15", "time": "14:30:00",
    "latitude": 28.6139, "longitude": 77.209,
    "timezone": "Asia/Kolkata", "place_name": "Delhi",
}

def call(path, payload, api_key=None, token=None):
    headers = {"Content-Type": "application/json"}
    if api_key:
        headers["X-API-Key"] = api_key
    if token:
        headers["Authorization"] = f"Bearer {token}"
    r = requests.post(f"{BASE}{path}", json=payload, headers=headers)
    r.raise_for_status()
    return r.json()

chart = call("/api/v1/chart/birth", birth)          # platform
chart = call("/api/dev/v1/vedic/chart/birth", birth, api_key="YOUR_KEY")  # dev API

JavaScript¶

async function callDevApi(path, payload, apiKey) {
  const res = await fetch(`http://127.0.0.1:8000${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": apiKey },
    body: JSON.stringify(payload),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

9. Rate limits & best practices¶

• Cache chart calculations: positions for a fixed birth time never change.
• Compute divisional charts client-side from D1 data when you only need a couple of vargas — or batch requests.
• Use GET /api/v1/location/search?q=<place> to resolve place names to lat/long/timezone before calling calculation endpoints.
• Always pass an explicit IANA timezone; fallback estimation is a convenience, not a precision guarantee.
• Respect 429 responses with exponential backoff.

10. Administration & monitoring¶

Admin endpoints live under /api/v1/admin/* (JWT + admin role):

• GET /api/v1/admin/dashboard/summary, /system-health, /tool-usage, /api-income, /consultations, /users, /payments, /refunds
• POST /api/v1/admin/flags/{flag_name} — toggle feature flags
• GET /api/v1/admin/flags — list flags

Full inventory in the API Reference.