# AstroLogics API: the full docs > Every docs page of https://developers.astrologics.in, in order. The index with links is https://developers.astrologics.in/llms.txt; the API contract is https://developers.astrologics.in/reference/openapi.yaml. # Quickstart Source: https://developers.astrologics.in/docs/quickstart ## 1. Get a test key [Create a free account](/auth/sign-up), open [API keys](/dashboard/keys) and create a **test** key. It starts with `al_test_`. Copy it when it is shown: we keep only a hash, so it is shown once. Test keys run the real engine and are never charged. Each project has a daily allowance of test calls ([rate limits](/docs/rate-limits)). ## 2. Make your first call This asks for the kundli of someone born in New Delhi on 13 August 1990 at 06:30. Replace `al_test_YOUR_KEY` with your key. ### curl 
curl -X POST 'https://api.astrologics.in/v1/kundli' \
  -H 'Authorization: Bearer al_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"birth":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}}}'
### Node.js 18 or later Save as `first-call.mjs` and run `node first-call.mjs`. 
const res = await fetch("https://api.astrologics.in/v1/kundli", {
  method: "POST",
  headers: { Authorization: "Bearer al_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "birth": {
      "date": "1990-08-13",
      "time": "06:30",
      "place": {
        "latitude": 28.6139,
        "longitude": 77.209
      }
    }
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));
### Python 3 Save as `first-call.py` and run `python3 first-call.py`. 
import json
import urllib.error
import urllib.request

body = {
    "birth": {
        "date": "1990-08-13",
        "time": "06:30",
        "place": {
            "latitude": 28.6139,
            "longitude": 77.209,
        },
    },
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/kundli",
    method="POST",
    headers={"Authorization": "Bearer al_test_YOUR_KEY", "Content-Type": "application/json"},
    data=json.dumps(body).encode(),
)
try:
    with urllib.request.urlopen(req) as res:
        print(json.dumps(json.load(res), indent=2, ensure_ascii=False))
except urllib.error.HTTPError as err:
    print(err.code, err.read().decode())
### PHP with the curl extension Save as `first-call.php` and run `php first-call.php`. 
<?php
$ch = curl_init('https://api.astrologics.in/v1/kundli');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer al_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"birth":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}}}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;
## 3. Read the response Every JSON response has the same envelope: - `data`: the result. - `meta`: `request_id` (quote it when you write to us), `engine_version` (it changes whenever a calculation changes), `mode` (`test` or `live`) and `credits_charged`. - `warnings`: anything you should know, such as fields left out because the birth time is unknown. Errors have one shape too: see [errors](/docs/errors). ## 4. Go live Create a **live** key when you are ready. Live keys spend your plan's credits, and only successful (2xx) calls are charged. Keep test and live keys on your server: never put them in a web page or a mobile app. For widgets, use a [publishable key](/docs/authentication#publishable-keys). Next: [the birth object](/docs/birth-input) · [API reference](/reference) Prefer a client library? See the quickstarts for [TypeScript](/docs/quickstart-typescript), [Python](/docs/quickstart-python) and [PHP](/docs/quickstart-php). # TypeScript quickstart Source: https://developers.astrologics.in/docs/quickstart-typescript You need Node.js 18 or later. The client has no dependencies and comes with type declarations for every operation. ## 1. Install The client is not on npm yet, so install this release from our site: ```bash npm install https://developers.astrologics.in/downloads/sdks/astrologics-typescript-0.1.0.tgz ``` ## 2. Set your key [Create a test key](/dashboard/keys). Test keys run the real engine and are never charged. ```bash export ASTROLOGICS_API_KEY=al_test_YOUR_KEY ``` Use a secret key only on a server, never in a web page or a [mobile app](/docs/mobile-apps). ## 3. Make your first call Save as `first-call.mjs` and run `node first-call.mjs`. ```js import { AstroLogics } from "astrologics"; const client = new AstroLogics({ apiKey: process.env.ASTROLOGICS_API_KEY }); const { data, meta } = await client.getKundli({ birth: { date: "1990-08-13", time: "06:30", place: { latitude: 28.6139, longitude: 77.209 } }, }); console.log(data.lagna.sign, meta.mode, meta.credits_charged); ``` It prints the lagna's sign, then `test 0`: the call ran in test mode and cost no credits. A place can also be a `place_id` or free text; see [the birth object](/docs/birth-input). ## 4. Save a chart Save as `save-chart.mjs`. An SVG operation returns a string, and a PNG or PDF operation returns a `Uint8Array`. ```js import { writeFile } from "node:fs/promises"; import { AstroLogics } from "astrologics"; const client = new AstroLogics({ apiKey: process.env.ASTROLOGICS_API_KEY }); const svg = await client.getChartSvg({ varga: "D1", birth: { date: "1990-08-13", time: "06:30", place: { latitude: 28.6139, longitude: 77.209 } }, }); await writeFile("chart.svg", svg); ``` ## 5. Handle errors Save as `handle-errors.mjs`. Any failed call throws an `ApiError`. Branch on `code`, not on the message, and quote `requestId` when you write to us. See [errors](/docs/errors). ```js import { AstroLogics, ApiError } from "astrologics"; const client = new AstroLogics({ apiKey: process.env.ASTROLOGICS_API_KEY }); try { await client.getKundli({ birth: { date: "1990-13-45" } }); } catch (e) { if (!(e instanceof ApiError)) throw e; console.log(e.status, e.code, e.requestId); for (const issue of e.issues) console.log(issue.param, issue.message); } ``` `ApiError` also carries `candidates` for an ambiguous place and `suggestions` for an unknown path. ## Retries and timeouts `429` and `5xx` answers are retried twice by default, honouring `Retry-After`. `quota_exhausted` is not retried. To change this, pass `maxRetries` and `timeoutMs` (default 60000) to the constructor. ## Find a method Each method is named after the operation's id in the [API reference](/reference), and its arguments are the operation's parameters and body, side by side. There is one method per public operation: 133 today. ## Go live Swap in a live key (`al_live_`) when you are ready. Live keys spend your plan's credits, and only successful calls are charged. Next: [SDKs](/products/sdks) · [Next.js tutorial](/docs/tutorial-nextjs) · [Python](/docs/quickstart-python) · [PHP](/docs/quickstart-php) # Python quickstart Source: https://developers.astrologics.in/docs/quickstart-python You need Python 3.8 or later. The client has no dependencies. ## 1. Install The client is not on PyPI yet, so install this release from our site: ```bash pip install https://developers.astrologics.in/downloads/sdks/astrologics-python-0.1.0.tar.gz ``` ## 2. Set your key [Create a test key](/dashboard/keys). Test keys run the real engine and are never charged. ```bash export ASTROLOGICS_API_KEY=al_test_YOUR_KEY ``` Use a secret key only on a server, never in a web page or a [mobile app](/docs/mobile-apps). ## 3. Make your first call Save as `first_call.py` and run `python3 first_call.py`. ```python import os from astrologics import AstroLogics client = AstroLogics(api_key=os.environ["ASTROLOGICS_API_KEY"]) result = client.get_kundli(birth={"date": "1990-08-13", "time": "06:30", "place": {"latitude": 28.6139, "longitude": 77.209}}) print(result["data"]["lagna"]["sign"], result["meta"]["mode"], result["meta"]["credits_charged"]) ``` It prints the lagna's sign, then `test 0`: the call ran in test mode and cost no credits. A place can also be a `place_id` or free text; see [the birth object](/docs/birth-input). ## 4. Save a chart Save as `save_chart.py`. An SVG operation returns a string, and a PNG or PDF operation returns `bytes`. ```python import os from astrologics import AstroLogics client = AstroLogics(api_key=os.environ["ASTROLOGICS_API_KEY"]) svg = client.get_chart_svg(varga="D1", birth={"date": "1990-08-13", "time": "06:30", "place": {"latitude": 28.6139, "longitude": 77.209}}) with open("chart.svg", "w", encoding="utf-8") as f: f.write(svg) ``` ## 5. Handle errors Save as `handle_errors.py`. Any failed call raises an `ApiError`. Branch on `code`, not on the message, and quote `request_id` when you write to us. See [errors](/docs/errors). ```python import os from astrologics import ApiError, AstroLogics client = AstroLogics(api_key=os.environ["ASTROLOGICS_API_KEY"]) try: client.get_kundli(birth={"date": "1990-13-45"}) except ApiError as e: print(e.status, e.code, e.request_id) for issue in e.issues: print(issue["param"], issue["message"]) ``` `ApiError` also carries `candidates` for an ambiguous place and `suggestions` for an unknown path. ## Retries and timeouts `429` and `5xx` answers are retried twice by default, honouring `Retry-After`. `quota_exhausted` is not retried. To change this, pass `max_retries` and `timeout` (in seconds, default 60) to the constructor. ## Find a method Each method is the operation's id from the [API reference](/reference) in snake case, so `getKundli` is `get_kundli`. Its keyword arguments are the operation's parameters and body, side by side. There is one method per public operation: 133 today. ## Go live Swap in a live key (`al_live_`) when you are ready. Live keys spend your plan's credits, and only successful calls are charged. Next: [SDKs](/products/sdks) · [TypeScript](/docs/quickstart-typescript) · [PHP](/docs/quickstart-php) # PHP quickstart Source: https://developers.astrologics.in/docs/quickstart-php You need PHP 8.0 or later with the curl and json extensions. The client has no other dependencies. ## 1. Install The client is not on Packagist yet, so download this release from our site and unpack it beside your code: ```bash curl -L https://developers.astrologics.in/downloads/sdks/astrologics-php-0.1.0.tar.gz | tar -xz ``` This creates the folder `astrologics-php-0.1.0`. ## 2. Set your key [Create a test key](/dashboard/keys). Test keys run the real engine and are never charged. ```bash export ASTROLOGICS_API_KEY=al_test_YOUR_KEY ``` Use a secret key only on a server, never in a web page or a [mobile app](/docs/mobile-apps). ## 3. Make your first call Save as `first-call.php` and run `php first-call.php`. ```php getKundli(['birth' => ['date' => '1990-08-13', 'time' => '06:30', 'place' => ['latitude' => 28.6139, 'longitude' => 77.209]]]); echo $result['data']['lagna']['sign'], ' ', $result['meta']['mode'], ' ', $result['meta']['credits_charged'], "\n"; ``` It prints the lagna's sign, then `test 0`: the call ran in test mode and cost no credits. A place can also be a `place_id` or free text; see [the birth object](/docs/birth-input). ## 4. Save a chart Save as `save-chart.php`. An SVG, PNG or PDF operation returns a string holding the file's content. ```php getChartSvg(['varga' => 'D1', 'birth' => ['date' => '1990-08-13', 'time' => '06:30', 'place' => ['latitude' => 28.6139, 'longitude' => 77.209]]]); file_put_contents('chart.svg', $svg); ``` ## 5. Handle errors Save as `handle-errors.php`. Any failed call throws an `ApiError`. Branch on `errorCode`, not on the message, and quote `requestId` when you write to us. See [errors](/docs/errors). ```php getKundli(['birth' => ['date' => '1990-13-45']]); } catch (\AstroLogics\ApiError $e) { echo $e->status, ' ', $e->errorCode, ' ', $e->requestId, "\n"; foreach ($e->issues as $issue) { echo $issue['param'], ' ', $issue['message'], "\n"; } } ``` `ApiError` also carries `candidates` for an ambiguous place and `suggestions` for an unknown path. ## Retries and timeouts `429` and `5xx` answers are retried twice by default, honouring `Retry-After`. `quota_exhausted` is not retried. To change this, pass `$maxRetries` and `$timeout` (in seconds, default 60) to the constructor, after `$baseUrl`. ## Find a method Each method is named after the operation's id in the [API reference](/reference). It takes one array holding the operation's parameters and body, side by side. There is one method per public operation: 133 today. ## Go live Swap in a live key (`al_live_`) when you are ready. Live keys spend your plan's credits, and only successful calls are charged. Next: [SDKs](/products/sdks) · [TypeScript](/docs/quickstart-typescript) · [Python](/docs/quickstart-python) # Next.js tutorial Source: https://developers.astrologics.in/docs/tutorial-nextjs You will build a page that takes a birth date, time and place, and shows the lagna, the planets and a chart image. The browser talks only to your own route, and the route holds the API key. You need Node.js 20 or later and a [test key](/dashboard/keys). Test keys run the real engine and are never charged. ## 1. Create the app ```bash npx create-next-app@latest kundli-demo --ts --app --no-tailwind --no-eslint --no-src-dir --yes ``` ```bash cd kundli-demo ``` ## 2. Install the client ```bash npm install https://developers.astrologics.in/downloads/sdks/astrologics-typescript-0.1.0.tgz ``` ## 3. Keep the key on the server Create `.env.local`. `create-next-app` already keeps `.env*` files out of git. ```bash ASTROLOGICS_API_KEY=al_test_YOUR_KEY ``` Do not give this variable a `NEXT_PUBLIC_` prefix. That prefix sends a value to the browser, and a secret key must never reach it. ## 4. Add the route Create `app/api/kundli/route.ts`. Birth details travel in the POST body, never in a URL. ```ts import { AstroLogics, ApiError } from "astrologics"; export async function POST(request: Request) { const { date, time, place, placeId } = await request.json().catch(() => ({})); const birth = { date, time, place: placeId ? { place_id: placeId } : { query: place } }; const client = new AstroLogics({ apiKey: process.env.ASTROLOGICS_API_KEY! }); try { const [kundli, chart] = await Promise.all([ client.getKundli({ birth }), client.getChartSvg({ varga: "D1", birth }), ]); return Response.json({ lagna: kundli.data.lagna, planets: kundli.data.planets, chart }); } catch (e) { if (!(e instanceof ApiError)) throw e; if (e.status === 400 || e.status === 422) { return Response.json({ error: e.message, candidates: e.candidates }, { status: 422 }); } console.error(e.code, e.requestId); return Response.json({ error: "The chart could not be calculated. Try again." }, { status: 502 }); } } ``` The route makes two calls: POST /v1/kundli (2 credits) and POST /v1/charts/{varga}.svg (2 credits). When a place name matches more than one place, the API answers `place_ambiguous` with `candidates`. It never guesses, so the page asks the user to choose. ## 5. Add the page Replace `app/page.tsx`. The chart goes in an `` as a data URL, so the page never inserts markup from a response into the document. ```tsx "use client"; import { useState, type FormEvent } from "react"; type Candidate = { place_id: string; name: string; state?: string; country?: string }; type Planet = { id: string; label: string; sign: string; house?: number; retrograde: boolean }; type Result = { lagna: { sign_label: string }; planets: Planet[]; chart: string }; export default function Home() { const [form, setForm] = useState({ date: "1990-08-13", time: "06:30", place: "New Delhi" }); const [result, setResult] = useState(null); const [candidates, setCandidates] = useState([]); const [error, setError] = useState(""); const [busy, setBusy] = useState(false); async function load(placeId?: string) { setBusy(true); setError(""); setCandidates([]); setResult(null); try { const res = await fetch("/api/kundli", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ ...form, placeId }), }); const body = await res.json(); if (res.ok) setResult(body); else { setError(body.error); setCandidates(body.candidates ?? []); } } catch { setError("Could not reach the server. Try again."); } finally { setBusy(false); } } function submit(e: FormEvent) { e.preventDefault(); load(); } const field = (name: keyof typeof form) => ({ value: form[name], onChange: (e: { target: { value: string } }) => setForm({ ...form, [name]: e.target.value }), }); return (

Kundli

{error &&

{error}

} {candidates.map((c) => (

))} {result && (

Lagna: {result.lagna.sign_label}

Birth chart {result.planets.map((p) => ( ))}
PlanetSignHouse
{p.label}{p.retrograde ? " (R)" : ""} {p.sign} {p.house ?? "–"}
)}
); } ``` ## 6. Run it ```bash npm run dev ``` Open `http://localhost:3000` and press **Show chart**. To see the place choices, enter a name that many places share. ## Before you go live - **Protect the route.** Anyone who can reach `/api/kundli` can spend your credits. Require sign-in or add a rate limit of your own first. - **Use a live key.** Set `ASTROLOGICS_API_KEY` to your `al_live_` key in your host's settings. Only successful calls are charged. - **Take care with birth details.** They are personal data. This route stores nothing and does not log them, so keep it that way unless you need to, and tell your users if you do. We [never write them](/docs/caching-and-data-retention) to our database or logs. - **Unknown birth times.** Add a way to send `time_accuracy`, rather than filling in a default time. See [the birth object](/docs/birth-input). Next: [TypeScript quickstart](/docs/quickstart-typescript) · [errors](/docs/errors) · [Flutter tutorial](/docs/tutorial-flutter) # Flutter tutorial Source: https://developers.astrologics.in/docs/tutorial-flutter You will build a screen that takes a birth date, time and place, and shows the lagna, the planets and a chart image. A secret key inside an app can be [extracted in minutes](/docs/mobile-apps), so the app talks to a small backend of yours and the backend holds the key. **How far this page is tested:** our test suite runs the backend below against the API's request chain, and checks that each field the Dart code reads is in the backend's answer. We compiled the Dart code as printed with Flutter 3.47.9, with no analyzer issues, but we have not yet run it on a phone. If you hit a problem, tell us at developers@astrologics.in. You need Node.js 18 or later, Flutter, and a [test key](/dashboard/keys). Test keys run the real engine and are never charged. ## 1. Create the backend ```bash mkdir kundli-backend ``` ```bash cd kundli-backend ``` ```bash npm init -y ``` ```bash npm install https://developers.astrologics.in/downloads/sdks/astrologics-typescript-0.1.0.tgz ``` Save this as `server.mjs`. Birth details travel in the POST body, never in a URL. ```js import { createServer } from "node:http"; import { AstroLogics, ApiError } from "astrologics"; const client = new AstroLogics({ apiKey: process.env.ASTROLOGICS_API_KEY }); function reply(res, status, body) { res.writeHead(status, { "Content-Type": "application/json" }); res.end(JSON.stringify(body)); } createServer(async (req, res) => { if (req.method !== "POST" || req.url !== "/kundli") return reply(res, 404, { error: "Not found" }); let raw = ""; for await (const chunk of req) raw += chunk; try { const { date, time, place, placeId } = JSON.parse(raw); const birth = { date, time, place: placeId ? { place_id: placeId } : { query: place } }; const [kundli, png] = await Promise.all([ client.getKundli({ birth }), client.getChartPng({ varga: "D1", birth }), ]); reply(res, 200, { lagna: kundli.data.lagna, planets: kundli.data.planets, chart_png: Buffer.from(png).toString("base64"), }); } catch (e) { if (e instanceof ApiError && (e.status === 400 || e.status === 422)) { return reply(res, 422, { error: e.message, candidates: e.candidates }); } console.error(e.code ?? e.name); reply(res, 502, { error: "The chart could not be calculated. Try again." }); } }).listen(process.env.PORT || 3000); ``` The backend makes two calls: POST /v1/kundli (2 credits) and POST /v1/charts/{varga}.png (3 credits). Start it with your key: ```bash ASTROLOGICS_API_KEY=al_test_YOUR_KEY node server.mjs ``` ## 2. Create the app In another terminal: ```bash flutter create kundli_app ``` ```bash cd kundli_app ``` ```bash flutter pub add http ``` ## 3. Call the backend Create `lib/kundli_api.dart`. ```dart import 'dart:convert'; import 'dart:typed_data'; import 'package:http/http.dart' as http; class Planet { Planet(this.label, this.sign, this.house, this.retrograde); factory Planet.fromJson(Map j) => Planet(j['label'] as String, j['sign'] as String, j['house'] as int?, j['retrograde'] == true); final String label; final String sign; final int? house; final bool retrograde; } class Kundli { Kundli(this.lagna, this.planets, this.chartPng); final String lagna; final List planets; final Uint8List chartPng; } class Candidate { Candidate(this.placeId, this.label); factory Candidate.fromJson(Map j) => Candidate( j['place_id'] as String, [j['name'], j['state'], j['country']].whereType().join(', '), ); final String placeId; final String label; } class KundliException implements Exception { KundliException(this.message, this.candidates); final String message; final List candidates; } class KundliApi { KundliApi(this.baseUrl, {http.Client? client}) : _client = client ?? http.Client(); final String baseUrl; final http.Client _client; Future fetch({required String date, required String time, required String place, String? placeId}) async { final res = await _client.post( Uri.parse('$baseUrl/kundli'), headers: {'Content-Type': 'application/json'}, body: jsonEncode({'date': date, 'time': time, 'place': place, 'placeId': placeId}), ); final j = jsonDecode(res.body) as Map; if (res.statusCode != 200) { final found = (j['candidates'] as List?) ?? const []; throw KundliException( j['error'] as String, found.map((c) => Candidate.fromJson(c as Map)).toList(), ); } return Kundli( (j['lagna'] as Map)['sign_label'] as String, (j['planets'] as List).map((p) => Planet.fromJson(p as Map)).toList(), base64Decode(j['chart_png'] as String), ); } } ``` ## 4. Add the screen Replace `lib/main.dart`. The backend's address comes from the command line, so it never gets typed into the code. ```dart import 'package:flutter/material.dart'; import 'kundli_api.dart'; const backendUrl = String.fromEnvironment('BACKEND_URL', defaultValue: 'http://localhost:3000'); void main() => runApp(const MaterialApp(title: 'Kundli', home: KundliScreen())); class KundliScreen extends StatefulWidget { const KundliScreen({super.key}); @override State createState() => _KundliScreenState(); } class _KundliScreenState extends State { final _api = KundliApi(backendUrl); final _date = TextEditingController(text: '1990-08-13'); final _time = TextEditingController(text: '06:30'); final _place = TextEditingController(text: 'New Delhi'); Kundli? _kundli; String? _error; List _candidates = const []; bool _busy = false; @override void dispose() { _date.dispose(); _time.dispose(); _place.dispose(); super.dispose(); } Future _load([String? placeId]) async { setState(() { _busy = true; _error = null; _candidates = const []; _kundli = null; }); try { final kundli = await _api.fetch(date: _date.text, time: _time.text, place: _place.text, placeId: placeId); if (mounted) setState(() => _kundli = kundli); } on KundliException catch (e) { if (mounted) { setState(() { _error = e.message; _candidates = e.candidates; }); } } catch (_) { if (mounted) setState(() => _error = 'Could not reach the server. Try again.'); } finally { if (mounted) setState(() => _busy = false); } } @override Widget build(BuildContext context) { final kundli = _kundli; return Scaffold( appBar: AppBar(title: const Text('Kundli')), body: ListView( padding: const EdgeInsets.all(16), children: [ TextField(controller: _date, decoration: const InputDecoration(labelText: 'Date (YYYY-MM-DD)')), TextField(controller: _time, decoration: const InputDecoration(labelText: 'Time (HH:MM)')), TextField(controller: _place, decoration: const InputDecoration(labelText: 'Place')), const SizedBox(height: 16), FilledButton( onPressed: _busy ? null : () => _load(), child: Text(_busy ? 'Calculating…' : 'Show chart'), ), if (_error != null) Padding(padding: const EdgeInsets.only(top: 16), child: Text(_error!)), for (final c in _candidates) TextButton(onPressed: () => _load(c.placeId), child: Text(c.label)), if (kundli != null) ...[ const SizedBox(height: 16), Text('Lagna: ${kundli.lagna}', style: Theme.of(context).textTheme.titleLarge), Image.memory(kundli.chartPng, semanticLabel: 'Birth chart'), for (final p in kundli.planets) ListTile( title: Text(p.retrograde ? '${p.label} (R)' : p.label), subtitle: Text(p.sign), trailing: Text(p.house == null ? '–' : 'House ${p.house}'), ), ], ], ), ); } } ``` ## 5. Run it On an iOS simulator, the default address reaches your computer: ```bash flutter run ``` On an Android emulator, your computer is at `10.0.2.2`: ```bash flutter run --dart-define=BACKEND_URL=http://10.0.2.2:3000 ``` ## Before you go live - **Host the backend over HTTPS** and pass its address as `BACKEND_URL` in your release build. - **Protect the backend.** Anyone who finds its address can spend your credits. Require sign-in or add a rate limit of your own first. - **Use a live key.** Set `ASTROLOGICS_API_KEY` to your `al_live_` key on the backend. It never goes in the app. - **Android release builds** need `` in `android/app/src/main/AndroidManifest.xml`. - **Take care with birth details.** They are personal data. This backend stores nothing and does not log them. We [never write them](/docs/caching-and-data-retention) to our database or logs. - **Unknown birth times.** Add a way to send `time_accuracy`, rather than filling in a default time. See [the birth object](/docs/birth-input). Next: [mobile apps](/docs/mobile-apps) · [errors](/docs/errors) · [Next.js tutorial](/docs/tutorial-nextjs) # Authentication Source: https://developers.astrologics.in/docs/authentication Send your key in the `Authorization` header of every request: Authorization: Bearer al_test_… These need no key at all: GET /v1/meta/conventions. ## Key kinds | Kind | Starts with | What it does | |---|---|---| | Test | `al_test_` | Real engine, never charged; `meta.mode` is `test`. Each project has a daily allowance of test calls, shared by all its test keys. | | Live | `al_live_` | Spends your plan's credits. Only successful (2xx) calls are charged. | | Publishable | `al_pub_` | For widgets in the browser: read-only operations without birth data, and only from the web origins you list. | Test and live keys are **secret**. Use them only from your server, never in a web page or a mobile app. ## Publishable keys A publishable key can call only these operations: The request's `Origin` header must exactly match one of the key's allowed origins, such as `https://www.example.com`. Otherwise the API answers `403 domain_not_allowed`. Any other operation answers `403 scope_not_allowed`. ## Rotating a key 1. On [API keys](/dashboard/keys), choose **Rotate**. A new key with the same name and settings is created, and the old one keeps working. 2. Deploy the new key. 3. Revoke the old key. It stops working on the next request. ## When a key is refused Missing, malformed, unknown, revoked and expired keys all get the same answer, `401 invalid_api_key`, so nobody can probe which keys exist. # The birth object Source: https://developers.astrologics.in/docs/birth-input Operations about a person take a `birth` object in the POST body. Birth data never goes in a URL.
  • date string (date) required

    e.g. "1990-08-13"

  • time string

    pattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ · e.g. "06:30"

  • time_accuracy string

    With "unknown", lagna- and house-dependent fields are omitted and listed in warnings — never filled with a noon default.

    one of exact, approximate, unknown · default "exact"

  • place Coordinates or object or object required

    Coordinates, a place_id from /v1/places/search, or a free-text query. A vague query returns 422 place_ambiguous with candidates; the API never guesses.

    One of:

    1. Coordinates
      Fields
      • latitude number required

        ≥ -90 · ≤ 90

      • longitude number required

        ≥ -180 · ≤ 180

      No other fields are accepted.

    2. object
      Fields
      • place_id string required

      No other fields are accepted.

    3. object
      Fields
      • query string required

        at least 2 characters · at most 120 characters

      No other fields are accepted.

  • timezone string

    "auto" (from coordinates AND date), an IANA name, or a fixed offset like "+05:30".

    default "auto"

No other fields are accepted.

## Place Send the place in one of three ways: - **Coordinates**, the most precise: `{ "latitude": …, "longitude": … }`. - **A place id** from [place search](/reference/places-and-time#searchPlaces): `{ "place_id": "pl_…" }`. - **A name**: `{ "query": "Noida" }`. - If nothing matches, the answer is `422 place_not_found`. - If several places match, it is `422 place_ambiguous`, with `error.candidates` to choose from. - The API never guesses. ## Timezone `timezone` defaults to `"auto"`: the zone and UTC offset in force **at that place on that date**, including historical changes. You can also send an IANA name (`"Asia/Kolkata"`) or a fixed offset (`"+05:30"`). The zone used comes back in `meta.timezone_used`. **Older dates in India.** With `"auto"`, India is +05:30 from 1906, and +06:30 from October 1941 to May 1942 and from September 1942 to October 1945. Before 1906 the timezone database has one zone for all of India, at +05:21, but cities kept their own local time then. For a birth before 1906, send a fixed offset if you know the time the clock was keeping. ## Time accuracy - `exact` (the default) and `approximate` compute everything. - `unknown` omits the fields that depend on the lagna or the houses and lists them in `warnings`. It never fills them with a noon default. - Operations that cannot work without a time answer `422 time_required`. ## Dates Dates must be between 1900-01-01 and 2100-12-31. # Errors Source: https://developers.astrologics.in/docs/errors Every error has the same shape, and its HTTP status matches its type:
  • error object required
    • type string required

      one of invalid_request, authentication_error, permission_error, not_found, conflict, rate_limit, api_error

    • code string required

      one of invalid_parameter, missing_parameter, unsupported_date_range, invalid_api_key, key_revoked, scope_not_allowed, plan_restricted, domain_not_allowed, not_found, idempotency_conflict, place_ambiguous, place_not_found, rate_limited, quota_exhausted, internal_error, engine_unavailable, timeout, time_required

    • message string required
    • param string
    • issues array of object
      Fields
      • param string required
      • message string required
    • candidates array of object
      Fields
      • place_id string required
      • name string required
      • state string
      • country string
    • suggestions array of object

      On a 404 for an unknown path: the operations you may have meant, most likely first. Absent when nothing is close.

      Fields
      • method string required
      • path string required
    • request_id string required
    • doc_url string (uri) required
- `issues` lists **every** problem in the request at once. - `candidates` comes with `place_ambiguous`. - `suggestions` can come with a `404` for an unknown path: the operations you may have meant, including the right method for the right path. It is absent when nothing is close. - `request_id`: quote it when you write to us. - `doc_url` links to the row for its code below. Errors are never charged. ## Error codes
CodeHTTPTypeMeaning
invalid_parameter400invalid_requestOne or more inputs are invalid; every problem is listed in error.issues.
missing_parameter400invalid_requestA required input is missing (the API currently reports these as invalid_parameter with issues). (reserved: not returned today)
unsupported_date_range400invalid_requestDates must be between 1900-01-01 and 2100-12-31.
invalid_api_key401authentication_errorMissing, invalid, revoked or expired API key.
key_revoked401authentication_errorRevoked keys get invalid_api_key instead, so a prober learns nothing. (reserved: not returned today)
scope_not_allowed403permission_errorThis key cannot call this operation; publishable keys may call only read-only operations without birth data.
plan_restricted403permission_errorEvery plan includes every operation, so this is not returned. (reserved: not returned today)
domain_not_allowed403permission_errorThe request's Origin is not one of this publishable key's allowed origins.
not_found404not_foundNo such operation or resource.
idempotency_conflict409conflictIdempotency keys are not supported yet. (reserved: not returned today)
place_ambiguous422invalid_requestMore than one place matches; choose one of error.candidates or send coordinates.
place_not_found422invalid_requestNo place matches; send coordinates or a place_id.
time_required422invalid_requestThis operation needs a birth time (time_accuracy exact or approximate).
rate_limited429rate_limitToo many requests per second, or too many at once, for your plan; retry after Retry-After seconds.
quota_exhausted429rate_limitThis period's credits (or a paid project's overage cap), or the project's daily test calls, are used up.
internal_error500api_errorSomething failed on our side; quote the request_id.
engine_unavailable500api_errorThe calculation engine is not reachable; not returned today because the engine runs in-process. (reserved: not returned today)
timeout500api_errorA calculation took too long; not returned today. (reserved: not returned today)
# Rate limits and credits Source: https://developers.astrologics.in/docs/rate-limits ## Plans
PlanCredits a monthRequests a secondRequests at onceWhen credits run outTest calls a day
Free3,00022Calls stop with 429 quota_exhausted100
Starter75,00054Calls continue as overage100
Growth4,00,000208Calls continue as overage100
Business15,00,0005016Calls continue as overage100
Limits apply per key: requests per second, and requests in flight at once. ## Headers Every authenticated response carries:
HeaderMeaning
RateLimit-LimitRequests allowed in the current window.
RateLimit-RemainingRequests left in the current window.
RateLimit-ResetSeconds until the window resets.
X-Credits-RemainingCredits left in the billing period.
A `429` also carries `Retry-After`, in seconds. ## Two kinds of 429 - `rate_limited`: too many requests per second or at once. Wait `Retry-After` seconds, then retry. - `quota_exhausted`: the period's credits are used up on a plan that stops at its allowance, a paid project's overage cap is reached, or the project's test calls for the day are used up. - Test calls reset at 00:00 UTC. - Credits reset at the start of each UTC month. - A paid project's overage cap is the plan's price unless you change it on the dashboard's Billing page. ## Credits per operation Only successful (2xx) calls are charged. Test keys are never charged.
OperationCredits
GET /v1/places/search Search birth places1
GET /v1/places/{place_id} Get one place1
GET /v1/places/reverse Nearest real settlement to coordinates1
POST /v1/timezone IANA zone and UTC offset at a moment and place1
POST /v1/kundli Birth chart: lagna and the nine grahas2
POST /v1/kundli/birth-details Avakhada birth details1
POST /v1/kundli/divisional Divisional charts D1–D602
POST /v1/kundli/aspects Graha drishti: houses and planets aspected1
POST /v1/kundli/yogas Yogas present, with strength and rule2
POST /v1/kundli/ashtakavarga Bhinna and Sarva Ashtakavarga, the bindus of the signs being transited, each planet's best and worst signs2
POST /v1/kundli/wealth Wealth reading from D1, D2, D9 and D10: hora placements, the D10 lagna and 10th lord, vargottama, scores 0–102
POST /v1/kundli/gemstones Gemstones by functional lordship: the lagna lord's, the 9th (or 5th) lord's, the mahadasha lord's, and those to avoid2
POST /v1/kundli/shadbala Shadbala: the six-fold strength of the seven grahas2
POST /v1/kundli/classical The classical layer: house cusps, bhava bala, prastara ashtakavarga, graha avasthas, sthira karakas, lucky points2
POST /v1/kundli/outer-planets Uranus, Neptune and Pluto: sidereal position, house from the lagna, and the house reading in English and Hindi2
POST /v1/kundli/d12 Dwadasamsa (D12) read for the lineage: father, mother, the 4th and 9th, strength 0–102
POST /v1/kundli/upagrahas Upagrahas: the five from the Sun, and Kala, Mrityu, Ardhaprahara, Yamaghantaka and Gulika from the day's eight parts1
POST /v1/kundli/arudha Arudha padas of the twelve houses, with Arudha Lagna and Upapada1
POST /v1/kundli/chara-karakas Jaimini chara karakas on the seven-planet scheme, with the karakamsha1
POST /v1/kundli/bhav-chalit Bhav chalit: the Sripati bhavas, and which planets shift from their rashi house1
POST /v1/planets/asta Asta and Uday: when each planet sets and rises near the Sun, for a place2
POST /v1/planets/series A series of sidereal positions over a range, at up to 400 steps2
GET /v1/reference/rashis The 12 rashis: span, lord, element, modality, varna, vashya and nakshatras1
GET /v1/reference/nakshatras The 27 nakshatras: span, lord, gana, yoni, nadi, deity and symbol1
POST /v1/planets/positions Sidereal positions at any moment and place1
GET /v1/planets/now The sky now: sidereal positions at the top of the current hour1
GET /v1/outer-planets/cycle The retrograde cycle of Saturn, Uranus, Neptune or Pluto: its stations and whether it is retrograde now1
POST /v1/kundli/bundle Several chart operations in one call: one rate-limit slot, charged their sum less one credit3
POST /v1/dasha/vimshottari Vimshottari periods to 5 levels2
POST /v1/dasha/vimshottari/current Running Maha → Antar → Pratyantar → Sookshma2
POST /v1/dasha/yogini Yogini dasha periods2
POST /v1/dasha/chara Jaimini Chara dasha and the karakas2
POST /v1/dosha/manglik Manglik: graded, from lagna, Moon and Venus, cancellations named1
POST /v1/dosha/kaal-sarp Kaal Sarp: none, partial or full1
POST /v1/dosha/sade-sati Sade Sati: is it running today, which phase, and when it ends1
POST /v1/dosha/sade-sati/timeline Every Sade Sati and Dhaiya of a lifetime: each sign leg with its phase, start and end2
POST /v1/match/ashtakoot Ashtakoot Guna Milan (36 points)1
POST /v1/match/dashakoot The ten South Indian poruthams, from the Moon stars: each result, a score, and Rajju called out1
POST /v1/match/papasamyam Papasamyam: malefics from lagna, Moon and Venus in both charts, compared2
POST /v1/match/manglik Manglik status of both and mutual cancellation2
GET /v1/panchang Panchang for a date and place1
GET /v1/panchang/choghadiya Day and night choghadiya1
GET /v1/muhurat/activities Supported muhurat activities0
GET /v1/muhurat/search Days rated for an activity, with scores and rejection reasons2
POST /v1/muhurat/personal Muhurat windows with tara bala and chandra bala for one person3
GET /v1/muhurat/day One day judged for an activity: the panchang, the verdict, the windows left after Rahu Kaal, Yamaganda and Gulika1
GET /v1/muhurat/{occasion}/year The dated muhurat list of a year for an occasion: the days that hold a window, with the windows2
GET /v1/muhurat/{occasion} Every local day between two dates for an occasion: available with its windows, or the reason it is not2
GET /v1/panchang/hora Hora: the 24 planetary hours of a day1
GET /v1/calendar/tithis Tithi start and end moments between two dates, and the tithi at each sunrise1
GET /v1/calendar/ekadashi Every Ekadashi of a year: the vrat date, the tithi and the paran window1
GET /v1/calendar/festivals Festivals of a year, each by its own rule, with its windows and moments2
GET /v1/horoscope/{sign} Horoscope for one sign1
GET /v1/horoscope All 12 signs (publisher feed)5
POST /v1/horoscope/personal A horoscope from the person's own Moon sign2
GET /v1/transits/events Planetary events: sign changes, retrograde stations and eclipses, with IST times1
GET /v1/transits Ingresses, stations and combustion between dates1
POST /v1/transits/natal Transits over the natal Moon and houses2
GET /v1/transits/graha-yuddha Graha yuddha (planetary war) now: Mercury, Venus, Mars, Jupiter and Saturn within 1.5°1
POST /v1/transits/aspects Exact conjunctions, sextiles, squares, trines and oppositions over a range2
POST /v1/transits/parallels Exact parallels and contra-parallels of declination over a range2
POST /v1/timing/personal Personal timing: today's score and band, the dasha–transit reading, a day-by-day strip and any red zone2
POST /v1/timing/dasha-transit Dasha–transit confluence: the running mahadasha and antardasha lords against their transit signs and houses2
POST /v1/timing/favourable-days Favourable days ahead by tara bala: the Moon's nakshatra counted from the birth nakshatra1
POST /v1/timing/year-outlook A 12-month outlook: the slow planets' transit houses from the lagna on the 15th of each month, scored2
GET /v1/horoscope/weekly/rashi-tones The week's tone for each rashi: a 0–100 score per day, the band, the best and worst days and the planet behind it1
POST /v1/muhurat/scan Scan up to 62 days for an activity inside daily hours: the ten best days with their favourable windows3
POST /v1/timing/eclipses The eclipses of the months ahead over the chart: sign, natal house, reading and shadow period2
POST /v1/numerology/core Life path, destiny, soul urge, personality (Chaldean)1
POST /v1/numerology/pythagorean Pythagorean numbers: core, karmic debts and lessons, pinnacles, challenges and personal year1
POST /v1/numerology/name Chaldean name number1
POST /v1/numerology/mobile Mobile-number analysis1
POST /v1/numerology/loshu Lo Shu grid1
POST /v1/numerology/compatibility Numerology compatibility1
POST /v1/numerology/business-name Business name number (Chaldean): planet, verdict and the business-friendly numbers1
POST /v1/numerology/lucky-name Is the name lucky for the person: the name number against the life path and birth numbers1
POST /v1/charts/{varga}.svg Chart as SVG (North or South Indian)2
POST /v1/charts/{varga}.png Chart as PNG (the same drawing as the SVG)3
POST /v1/reports/kundli.pdf A client-ready kundli as a PDF, under your name, logo and colour10
POST /v1/reports/match.pdf A client-ready matching report as a PDF: Ashtakoot, Dashakoot and Manglik10
POST /v1/reports/vastu.pdf A client-ready Vastu report as a PDF: mandala, plot, door and rooms10
POST /v1/kp/chart KP chart: cusps and planets with star, sub and sub-sub lords2
POST /v1/kp/significators KP 4-step significators and house groups2
GET /v1/kp/ruling-planets The seven KP ruling planets at a moment and place1
GET /v1/kp/horary KP horary (prashna) for a number from 1 to 2492
POST /v1/kp/changes When each planet changes sign, star lord or sub lord over a range2
POST /v1/kp/ruling-intervals The seven KP ruling planets over a window, as intervals2
POST /v1/lal-kitab/chart Lal Kitab teva: houses, planet states, sleeping houses2
POST /v1/lal-kitab/debts The nine Lal Kitab rin (debts), graded1
POST /v1/lal-kitab/varshphal Lal Kitab annual chart for a year of life2
POST /v1/lal-kitab/remedies Lal Kitab remedies, in the order to do them1
POST /v1/varshaphal Tajik varshaphal: annual chart, muntha, year lord, Mudda dasha3
POST /v1/biorhythm/reading The three cycles on a date, with their state, trend, next critical date and meaning1
POST /v1/biorhythm/forecast The three values for each day of a range, ready to chart1
POST /v1/biorhythm/critical-days The dates a cycle crosses zero, marked single, double or triple1
POST /v1/biorhythm/compatibility How far two people's cycles sit apart, scored for each cycle1
POST /v1/biorhythm/phases Where each cycle is: its half, when that half began and ends, and the next peak and trough1
POST /v1/biorhythm/daily A short daily summary with the coming week's values1
POST /v1/forecast/timeline Dasha changes, Sade Sati and Dhaiya, and Jupiter, Saturn and Rahu sign changes, in date order3
POST /v1/forecast/transits Sign changes and the minutes a transiting planet reaches or opposes a natal point2
POST /v1/forecast/significant-dates The larger dates in a range: dasha changes, Saturn's periods, and Saturn, Jupiter and Rahu returns3
POST /v1/forecast/digest One month for a chart: the running periods, where the planets stand and the month's dated events2
POST /v1/forecast/solar-return The minute the Sun returns to its birth longitude in a year, with the chart for that minute2
POST /v1/western/chart A tropical birth chart: planets, angles, Placidus or other houses, dignities and element balance2
POST /v1/western/chart.svg The chart drawn as a wheel in SVG, with the ascendant on the left2
POST /v1/western/aspects Natal aspects with their orbs, and whether each is applying1
POST /v1/western/synastry Aspects between two charts, and each person's planets in the other's houses3
POST /v1/western/composite A midpoint composite chart for two people3
POST /v1/western/transits Exact transits to a birth chart, sign ingresses and stations over a range3
POST /v1/western/progressions A secondary progressed chart for a date, with solar arc angles2
POST /v1/western/solar-return The tropical solar return chart for a year, at the birth place or another2
POST /v1/western/lunar-return The next tropical lunar return chart after a date2
POST /v1/chinese/bazi The four pillars with hidden stems, ten gods, nayin and element counts2
POST /v1/chinese/luck-pillars The ten-year luck pillars, their direction and the age they start1
POST /v1/chinese/annual A solar year's pillar against a chart: Tai Sui, relations and the twelve month pillars1
POST /v1/chinese/compatibility Harmonies and conflicts between two charts' year and day pillars1
POST /v1/chinese/zodiac The birth year animal by Li Chun and by Lunar New Year, and whether they agree1
POST /v1/chinese/date A Gregorian date in the Chinese calendar: lunar month and day, leap month, day pillar and solar term1
POST /v1/chinese/solar-terms The 24 solar terms of a year, to the minute1
POST /v1/feng-shui/kua A person's Kua number, East or West group and eight directions1
POST /v1/feng-shui/house A building's gua from its facing, its eight mansions, and how it fits an occupant's Kua1
POST /v1/feng-shui/flying-stars A Xuan Kong flying star chart: base, mountain and water stars in all nine palaces, and its structure2
POST /v1/feng-shui/flying-stars.svg The flying star chart drawn as a nine-palace grid in SVG, south at the top2
POST /v1/feng-shui/annual A year's flying stars, Five Yellow, Tai Sui, Sui Po and San Sha, with the twelve monthly charts1
GET /v1/vastu/reference The 32 padas with their door effects and verses, the 45 devatas, the room rules and the score's weights1
POST /v1/vastu/mandala The Vastu Purusha Mandala over a real plot: every square in metres, the brahmasthan, the vamsa lines and the atimarma points2
POST /v1/vastu/mandala.svg The mandala drawn as SVG, north up, in English or Hindi, with the door marked2
POST /v1/vastu/entrance Which of the 32 padas a door falls on, the text's effect and verse, and the better stretches of wall1
POST /v1/vastu/ayadi The Ayadi formulas on a building's measures: every working shown, the yoni judged, and nearby measures that pass1
POST /v1/vastu/plot Findings on a plot: proportion, shape, slope, water, cut corners, extensions and roads, each classical or convention1
POST /v1/vastu/rooms A verdict for each room by zone, what to prefer, and a score with published weights1
GET /v1/usage Credits used and remaining this period0
GET /v1/meta/conventions Defaults and conventions (ayanamsa, node, sunrise definition, what is not computed)0
# Conventions Source: https://developers.astrologics.in/docs/conventions These come straight from [`GET /v1/meta/conventions`](/reference/platform#getConventions), which needs no key.
engine_version
2026.10.10
ayanamsa
lahiri
kp_ayanamsa
kp_new (Lahiri − 5′24″)
house_system
whole_sign
node
true
sunrise
upper limb, refracted
moonrise
the Moon's centre on the true horizon (festival moments; the panchang does not give moonrise)
lunar_month
amanta (new moon to new moon); purnimanta names alongside
ayanamsa_options
lahiri (default), raman, krishnamurti, yukteshwar, fagan_bradley: options.ayanamsa on chart operations; the calendar, panchang and KP are unaffected
not_computed
moonrise in the panchang, yoga/karana end times, Vaishnava paran (Ekadashi), Vaishnava Janmashtami, Ghatak Chakra, Chara-dasha antardashas
Whenever a calculation changes, `meta.engine_version` changes too. ## Vimshottari periods The balance at birth comes from the Moon's position in its nakshatra. Sub-periods divide each period in proportion to the lords' years. The first mahadasha was already running at birth, so the sub-periods before birth are skipped, and the first one returned is the one running at birth. ## Ashtakoot tables Almanacs differ slightly on these tables, so treat them as a convention. We use: - **Yoni:** the 14 by 14 grid printed by [The Vedic Horoscope](https://www.thevedichoroscope.com/marriage-astrology/horoscope-matching-marriage). Where it prints two values for a pair, we use the higher. - **Vashya, Graha Maitri, Gana and Tara:** the rules in [AstroMedha's Ashtakoota guide](https://astromedha.in/insights/vedic/ashtakoota-guna-milan). Gana depends on who is the groom and who is the bride. - **Vashya classes:** one class for each sign, so Sagittarius is Manava and Capricorn is Jalachara throughout. Some traditions split these two signs in half. # Accuracy Source: https://developers.astrologics.in/docs/accuracy We compare the engine's planetary longitudes with **NASA JPL Horizons** (DE441), the reference used by professional astronomers, for every body at regular dates across 1900–2025. The differences below are in arc-seconds (″); one degree is 3,600″.
BodyMedian ″Max ″
Sun0.381.63
Moon0.924.05
Mercury1.449.47
Venus1.1313.8
Mars1.019.42
Jupiter2.359.40
Saturn2.3311.0
Uranus3.1811.6
Neptune11.318.5
Pluto1.793.66
These are ephemeris differences only: for dates after 2025 both sides predict ΔT (the Earth's clock drift), and their predictions diverge, which is a model choice rather than an error. ## Chart-level checks Every change to the engine must reproduce all 291 golden charts exactly (lagna, all nine grahas, nakshatras, houses, dashas) before it can ship. A calculation change that alters any of them is announced in the [changelog](/changelog) with the new `engine_version`. ## Check it yourself Download the test set (JSON): every date, body, the JPL longitude, our longitude and the difference. # Pythagorean numerology Source: https://developers.astrologics.in/docs/pythagorean `/v1/numerology/pythagorean` follows the rules [Hans Decoz publishes](https://www.worldnumerology.com/numerology-software/decoz-software-7-calculations.html). This is a modern Western system and nothing Pythagoras wrote. The other numerology operations stay Chaldean. Numerologists disagree on methods, so these are the choices: - **Letters:** A=1 to I=9, J=1 to R=9, S=1 to Z=8. Accents are removed. A name without Latin letters is refused. - **Life path:** month, day and year are reduced separately, keeping 11, 22 and 33, then added and reduced. This is Decoz's Method A. Adding all the digits together can give a different answer. - **Name numbers:** each name is reduced by itself, then the results are added. Send the full name at birth, without titles or suffixes. - **Y:** a vowel, unless it follows a vowel or starts a name before one (Maya, Yemen). W is always a consonant. There is no override for a single letter. - **Karmic debt:** 13, 14, 16 or 19 met while reducing the life path, expression, soul urge or personality, plus a birthday on one of those days and the digit sum of the birth year. The source does not spell out the rule for names, so applying it there is our reading. - **Pinnacles:** the first ends at 36 minus the life path, with a master counted as its single digit. The next two last nine years each, and `to_age` is null on the last. - **Challenges:** master numbers are reduced first. `main` is the third challenge. - **Personal year and month:** from `as_of`, by calendar year, reduced to one digit. Personal day is left out because the pages give no rule. The source does not give meanings in a form we can reuse, so `meanings` come from our own number table, shared with the Chaldean operations and without its planets. Answers are in English only. # South Indian matching Source: https://developers.astrologics.in/docs/south-indian-matching `/v1/match/dashakoot` and `/v1/match/papasamyam` follow common practice as published sources state it. We have not read a classical text for either, and regional almanacs differ, so every answer carries `basis: convention`. In both, `person_a` is the groom and `person_b` the bride: the rules are not the same in each direction. ## The ten poruthams Stars and signs are the Moon's. Counts run from the bride's to the groom's, with hers counted as 1. Without a birth time, the Moon is taken at 12:00 and a warning says so. | Porutham | Agrees | Moderate | | --- | --- | --- | | Dina | The count divided by 9 leaves 2, 4, 6, 8 or 0 | | | Gana | Same gana | Deva with Manushya | | Mahendra | Count of 4, 7, 10, 13, 16, 19, 22 or 25 | | | Stree Deergha | Count above 13 | Count above 9 | | Yoni | Any pair not listed as hostile | | | Rasi | Count of 1, 7, 9, 10 or 11 | Count of 12 | | Rasi Adhipati | Same lord, or friends both ways | Anything else, unless enemies both ways | | Vashya | Same class | Neighbouring class | | Rajju | Different rajju | | | Vedha | Not a vedha pair | | Every other case does not agree. The rules for Dina, Mahendra, Stree Deergha, Rasi, Rajju and Vedha follow [HinduTone's guide](https://hindutone.com/astrology/porutham-10-poruthams-south-indian-marriage-matching/). The score of 1, 0.5 or 0 follows [Tamilcube's calculator](https://astrology.tamilcube.com/porutham/). These choices are ours: - **Gana, Rasi Adhipati:** the guide only urges caution on Rakshasa pairs, and does not cover a friend paired with an enemy. We count Rakshasa with another gana as not agreeing, and the mixed pairs as moderate. - **Rasi:** count 12 is moderate because the guide says many astrologers are cautious about 2/12. Other sources accept 8; we follow the guide, which avoids 6/8. - **Vashya:** published tables of vashya signs conflict, and we could not confirm one. We use the same five classes as our Ashtakoot, so this differs from a Tamil panchangam's sign table. - **Yoni, gana, lords:** these use the tables our Ashtakoot already uses. - **Counting:** the guide says the bride's star counts as 1 only for Dina. We use the same count for the others. `meets_minimum` needs Rajju to agree and at least `minimum_agreeing` poruthams to agree. Sources name 5, 6 or 7, and one names no minimum at all, so the default of 5 is a setting and not a ruling. ## Papasamyam Sources agree on the method. For each chart, take Sun, Mars, Saturn and Rahu, and see which fall in houses 1, 2, 4, 7, 8 or 12 from the lagna, the Moon and Venus, by whole signs. Compare the totals: the result is satisfactory when the groom's total is equal or higher. Both birth times are needed. They disagree on the points, so you choose with `method`: | `method` | Points | From | | --- | --- | --- | | `count` | 1 for each placement | [Astrologymag's worked table](https://astrologymag.com/papa-samyam-in-horoscope-matching-kundali-milan/), which our test reproduces | | `weighted` | House units (3, 3, 3, 5, 6, 1) times planet units (Rahu 1, Sun 2, Saturn 3, Mars 4), half from the Moon, a quarter from Venus, then scaled by dignity | [A 2014 article by an astrologer](https://sreenivasdesabhatla.wordpress.com/2014/05/29/dosha-samyam-papamyam-in-matching/) | The weighted dignity shares are exalted 0, moolatrikona 1/4, own sign 1/2, friend's sign 3/4 and debilitated 5/4. The article gives no share for other signs, and no dignity for Rahu, so we use full points for both. The dignity tables themselves are the standard ones. What we leave out, because the sources conflict: - **Ketu:** some sources count it. `include_ketu` adds it with `count`; the weighted article gives it no dosha. - **Margin:** one source allows a groom's total of up to twice the bride's, and another 1.25 times. We report `ratio_groom_to_bride` and judge only which total is higher. - **Averaging, Jupiter's aspect, star exemptions:** [another source](http://brahmanasamskara.blogspot.com/2009/05/preliminary-screening-of-horoscopes-for_14.html) averages the three references and lets Jupiter's aspect cancel points. These are not applied. - **Comparing methods:** totals from `count` and `weighted` are on different scales. Hindi covers the labels and sentences. Star, sign and planet names in the rows stay in English. # Vastu conventions Source: https://developers.astrologics.in/docs/vastu The [Vastu operations](/products/vastu) take a plot's measurements. They never ask for an address or birth details. ## The text Apart from [Ayadi](#ayadi), classical rules come from one text: Varahamihira's *Brihat Samhita*, chapter 53, in N. Chidambaram Iyer's 1884 English translation, which is in the public domain. Each classical answer carries its verse in `source`, as `verses`. Numbers can differ in other editions. Each answer has a `basis`: - `classical`: the chapter says it, and `source` names the verse. - `convention`: the chapter does not say it. It is present-day practice, or a choice of ours, and `source` is `null`. Effects are the text's traditional statements, shortened. They are not predictions or building advice. Where the text's wording turns on caste or on women's character, we use plainer words; the verse is there for anyone who wants the original. ## Measuring a plot | Field | Meaning | | --- | --- | | `width_m` | Along the front | | `depth_m` | From the front to the back | | `facing_deg` | The bearing you look along facing out through the front: 0 north, 90 east | `left` and `right` are as seen from outside, looking at the front. A door's `from_left_m` runs from the left end of its wall, as seen from outside that wall. The mandala sits on the plot's own sides, and each side takes the name of the nearest compass direction. Beyond 15° from a direction, the answer carries a `plot_not_cardinal` warning: the text assumes sides that face the four directions. ## The two grids **81 squares.** Verses 42 to 50 place all 45 gods. The door's pada follows the squares: a wall has nine, and the ninth is the corner, which is the first pada of the next side. **64 squares.** Verses 55 and 56 give the classes of square and the two diagonals, but name no inner god square by square, so those squares return their class only. We read the perimeter from verse 71, which applies the door effects to either grid: eight stretches to a wall, with each corner shared by two gods. That reading is ours. ## Three slips we read past Verse 43 swaps two corners; verses 44 and 45 settle 81 as south-west and 73 as north-west. Verse 50 gives 33 for Prithvidhara where verse 47 gives 39. Some printings of verse 63 give 65 for Mukhya where verses 44 and 45 give 55. With these read that way, the six lines of verse 63 cross in the nine points verse 64 states, which the tests check. ## Rules we do not apply Verse 116 allows the east or north to stand slightly higher if it cannot be avoided, while verse 117 warns against either. We report verse 117's warning and do not relax it. Rules in this chapter sorted by caste are left out. ## The rooms' score The text places five rooms (verse 118) and protects the centre (verse 66). Only the ideal zone of those five is classical; the acceptable and avoid lists, and all the other room types, are convention. The score is ours, and `data.scoring` gives its weights. A room's position is turned into a zone by dividing the plot in thirds both ways, also ours. ## Ayadi The formulas come from a modern study, not from our own reading of the Sanskrit: D. N. Shukla, *Vastu-shastra* (1960), chapter 6, which reproduces them from Mallaya. `source.via` says so on each answer. Texts differ, so you choose with `system`: | `system` | Follows | Measures used | | --- | --- | --- | | `manasara` | Manasara | Length, breadth and circumference | | `perimeter_texts` | Kashyapa Shilpa, Shilparatna, Vastuvidya, Manushyalaya Chandrika, Samarangana Sutradhara | Perimeter, with two forms of vyaya | | `utpala` | Utpala on *Brihat Samhita* | Length times breadth, for the yoni only | Each result shows its base, multiplier, divisor and remainder, so it can be checked by hand. - **Cubits:** measures are in hasta. For metres, send your own `hasta_cm`. Texts and regions differ on its length, so we do not pick one. - **Yoni:** odd is good, even is bad and Dhvaja is best, as the source says. No remainder means the measures should change. - **Aya over vyaya:** the source says these show gain and loss, but does not state this comparison. It is common practice, so it is labelled `convention`. - **No remainder elsewhere:** we read it as the group's last member. The source says this only for the yoni. - **Rksha, vara, tithi and vayas:** reported without a verdict, because the source gives none. - **`nearby_passing`:** whole-cubit measures close to yours that pass. The search is ours; the formulas exist to choose among measures. ## Griha pravesh Griha pravesh dates are already in [dated muhurat lists](/reference/panchang-and-muhurat). # Vedic additions Source: https://developers.astrologics.in/docs/vedic-additions We have not read the Sanskrit texts for these operations, so their answers carry `basis: convention`, and each section names what it follows. ## Upagrahas `/v1/kundli/upagrahas` follows the formulas and tables on [Wikipedia's Upagraha page](https://en.wikipedia.org/wiki/Upagraha). - **From the Sun:** Dhuma is the Sun plus 133°20', Vyatipata 360° minus Dhuma, Parivesha Vyatipata plus 180°, Indrachapa 360° minus Parivesha, and Upaketu Indrachapa plus 16°40'. - **From the day:** sunrise to sunset, or sunset to sunrise, is cut into eight parts, each ruled by a planet with the weekday's own first. At night the first part goes to the 5th planet from the weekday's. Each point is the lagna at the end of its planet's part. - **Before sunrise:** a birth before sunrise belongs to the night of the previous weekday. - **Gulika and Mandi:** the page treats them as one point, so there is one row, `gulika`. Some astrologers separate them; if yours does, this is not their Mandi. The page also lists ghati figures that don't quite match its own table. We follow the table, which scales with the real length of the day. ## Arudha padas `/v1/kundli/arudha` follows the rule on [Wikipedia's Lagna page](https://en.wikipedia.org/wiki/Lagna): count from a sign to its lord, then count as many signs again from the lord. - **Barred signs:** the pada can't be the sign itself or its 7th. Then it is the 10th from the barred sign. The page's own example gives a different reading, but that one lands on a barred sign, so we don't follow it. - **Upapada:** the pada of the 12th house. - **Scorpio and Aquarius:** each has two possible lords. We found no rule we could confirm for choosing by strength, so the default is Mars and Saturn, and you can send `scorpio_lord: ketu` or `aquarius_lord: rahu`. ## Asta and Uday `/v1/planets/asta` tests each day at the place you send. It measures how far ahead of the Sun the planet rises and how far behind it sets, in time-degrees (1 degree = 4 minutes). A planet is in Asta while neither gap reaches its degrees. `asta` and `uday` are the sunrise or sunset of that first day, so they are place-dependent and only as exact as the day. | Planet | Degrees | Retrograde | From | | --- | --- | --- | --- | | Jupiter | 11 | | [Drik Panchang's Asta pages](https://www.drikpanchang.com/planet/asta/guru-asta-date-time.html), quoting Surya Siddhanta | | Saturn | 15 | | The same | | Venus | 10 | 8 | The same | | Mars | 17 | | Our combustion orb | | Mercury | 14 | 12 | Our combustion orb | The Moon isn't included. Drik Panchang says its own dates use modern algorithms, and ours differ. This is how far we were from it at New Delhi, which our tests pin: | Period (Drik's dates) | Asta differs by | Uday differs by | | --- | --- | --- | | Jupiter, 12 Jun to 9 Jul 2025 | 2 days | Same day | | Jupiter, 15 Jul to 12 Aug 2026 | 2 days | Same day | | Saturn, 13 Mar to 22 Apr 2026 | 3 days | Same day | | Venus, 19 to 23 Mar 2025 | Same day | 1 day | | Venus, 12 to 29 Oct 2026 | 2 days | 1 day | | Venus, 11 Dec 2025 to 1 Feb 2026 | 9 days | 13 days | Our periods run longer than Drik's. Use a panchang's dates when you need to match that panchang. Mars and Mercury have no comparison yet, and a change of orb when Mercury turns retrograde can split one period into two. This is not a forecast of when a planet can be sighted: it has no atmosphere or brightness model. ## Series and reference tables - **`/v1/planets/series`:** geocentric sidereal positions at each step from 00:00 UTC on `from`, up to 400 points. - **`/v1/reference/rashis` and `/v1/reference/nakshatras`:** the same tables our other operations use. Deity and symbol come from [Wikipedia's List of Nakshatras](https://en.wikipedia.org/wiki/List_of_Nakshatras), in English. Abhijit is left out. # More Vedic and KP Source: https://developers.astrologics.in/docs/vedic-more These six operations return positions and moments. Only the karaka scheme is a choice of school. ## Chara karakas `/v1/kundli/chara-karakas` ranks the seven planets by degrees in their sign, highest first, and returns the karakamsha. Rahu is not counted. Schemes with eight karakas exist and give different roles, so the answer carries `scheme: seven` and `basis: convention`. ## Bhav chalit `/v1/kundli/bhav-chalit` returns the Sripati bhavas, with the madhya of the 1st at the lagna and of the 10th at the midheaven. Each arambh is halfway between two madhyas. Each planet shows its whole-sign house, its bhava and whether the two differ. ## KP changes and ruling planets `/v1/kp/changes` lists when each planet moves to a new sign, star lord or sub lord, on the KP-New ayanamsa that [`/v1/kp/chart`](/reference) uses. A retrograde planet can return across a boundary, and that appears as its own change. `/v1/kp/ruling-intervals` reads the seven ruling planets for each minute of a window at a place and joins the minutes that agree. The lagna's sub lord can change every few minutes, so expect many intervals. ## Exact aspects and parallels `/v1/transits/aspects` finds the moment two planets reach an exact angle of ecliptic longitude. These are angular aspects and not graha drishti, which [`/v1/kundli/aspects`](/reference) returns. Set `include_moon` for lunar aspects. `/v1/transits/parallels` finds the moment two planets share a geocentric declination, or the same declination on opposite sides of the equator. It takes no orb. ## Limits and accuracy Times are UTC, to the minute. Ranges are at most 366 days, or 31 with the Moon. Ruling planet windows are at most 6 hours. | Check | Published or searched value | Our answer | |---|---|---| | Jupiter and Saturn in ecliptic longitude, December 2020 | 18:20:29 UTC on 21 December ([IMCCE](https://www.imcce.fr/newsletter/medias/2020/12/docs/conjonctions.pdf)) | 18:26 UTC, about 6 minutes later | | New and full moons, March 2026 | The ephemeris library's own phase search | Within 6 minutes (tested) | Tests hold both to within 6 minutes, so treat these times as accurate to several minutes. # Versioning and calculation changes Source: https://developers.astrologics.in/docs/versioning-and-calculation-changes - **API version:** every path starts with `/v1`. Within `v1` we only **add**: new operations, new optional parameters, new response fields. Removing or renaming anything needs a new version, announced in advance. - **Engine version:** every JSON response carries `meta.engine_version`. It changes when a calculation changes, even if the response shape does not. - **Calculation changes** are listed separately in the [changelog](/changelog) (with an [RSS feed](/changelog.rss)): what changed, why, and which results move. Store `engine_version` with results you keep, so you know which rules produced them. # Biorhythm Source: https://developers.astrologics.in/docs/biorhythm Biorhythm counts whole days from the date of birth and reads three sine waves. It needs no birth time, place or ephemeris. | Cycle | Period | Value on day t | |---|---|---| | Physical | 23 days | 100 × sin(2πt ÷ 23) | | Emotional | 28 days | 100 × sin(2πt ÷ 28) | | Intellectual | 33 days | 100 × sin(2πt ÷ 33) | The formula is the one in [Cleve Moler's MathWorks post on biorhythms](https://blogs.mathworks.com/cleve/?p=105). The day of birth is day 0. ## What the evidence says Controlled studies have not found that biorhythm predicts events. [Hines (1998), "Comprehensive review of biorhythm theory", Psychological Reports 83, 19–64](https://brianmac.co.uk/biorhythms.htm) is the review usually cited. Every reading returns a `note` that says this. Keep it visible in your product, and do not use biorhythm for safety, medical or hiring decisions. ## Critical days A cycle crosses zero every half period. With 23 and 33 days that can fall between two dates, for example at day 11.5. We call a date critical when a crossing falls between its start and the start of the next date, so day 11.5 marks day 11. This rule is a convention. Other charts may mark the next date as well. `crossing_day` gives the exact point, so you can apply your own rule. ## Compatibility Two people's waves stay the same distance apart for life, so `/v1/biorhythm/compatibility` takes no date. Each score is 50 × (1 + cos(2π × days apart ÷ period)): 100 when in step, 0 when exactly opposed. This scale is our convention, and the response labels it so. ## Language and data Set `lang` to `hi` for Hindi names, meanings and notes. The dates of birth are used for the response and not stored. # Caching and data retention Source: https://developers.astrologics.in/docs/caching-and-data-retention ## What we keep Request bodies are **never written** to our database or logs. The web server's access log records each request line, including its query string, for up to 8 days, so send birth details in a POST body. For each call we also keep the request id, the operation, the status, the latency, the credits and which key made it (for your usage page and request logs), for 90 days. The [privacy policy](/legal/privacy) has the full list. ## What you may cache Results for a given input do not change while `meta.engine_version` stays the same, so you may cache them as long as you like. Birth charts, divisional charts and doshas are ideal to store once per user. Daily panchang and horoscopes change by date and place, so cache them per day. # White-label reports Source: https://developers.astrologics.in/docs/reports Three operations return a finished A4 PDF that you can send to a client. Your name, logo, colour and contact details are on every page, and ours appear nowhere in the document. | Operation | Contains | Credits | |---|---|---| | `POST /v1/reports/kundli.pdf` | D1 and D9 charts, avakhada, planets, Vimshottari mahadashas, yogas and doshas | 10 | | `POST /v1/reports/match.pdf` | Ashtakoot, Dashakoot and Manglik for both people | 10 | | `POST /v1/reports/vastu.pdf` | Mandala and plot, plus the ground, door and rooms if you send them | 10 | ## Your branding ```json { "brand": { "name": "Sample Jyotish Studio", "tagline": "Consultations by appointment", "contact": "hello@example.com", "color": "#1f4e79", "logo_base64": "iVBORw0KGgo..." } } ``` Only `name` is required. The logo is a PNG or JPEG in base64, up to about 150 KB. Send the image itself, because we do not fetch URLs. ## Languages Set `lang` to `en` or `hi`. - **Vastu:** Hindi throughout. - **Kundli:** labels and tables are Hindi. Yoga names and rules, and dosha notes, stay in English, because we hold no reviewed Hindi for them. - **Matching:** labels and Dashakoot are Hindi. Ashtakoot and Manglik notes stay in English, for the same reason. Hindi text prints correctly, but copying it out of the PDF may not give clean text. ## Your clients' data The PDF is built in memory for one response. We do not store it, or the names, birth details or logo you send. Each report ends with a short note that it is guidance and does not replace professional advice. ## Saving the file ```bash curl -X POST https://api.astrologics.in/v1/reports/kundli.pdf \ -H "Authorization: Bearer $ASTROLOGICS_KEY" -H "Content-Type: application/json" \ -d @request.json -o report.pdf ``` # Forecast Source: https://developers.astrologics.in/docs/forecast These operations return dated facts about a chart. They say what happens and when, not what it will bring. If you add interpretation, it is yours to write and to stand behind. All of them need a birth time. ## What each one returns - `/v1/forecast/timeline`: dasha and antardasha changes, the start and end of Sade Sati and Dhaiya, and sign changes of Jupiter, Saturn and Rahu. At most 5 years. - `/v1/forecast/transits`: sign changes, and the minute a transiting planet reaches or opposes a natal planet or the lagna. At most 366 days, or 31 with the Moon. A retrograde planet can reach the same degree three times. - `/v1/forecast/significant-dates`: the larger dates over at most 10 years. The `major` and `notable` weights are our convention, and the response states the rule. - `/v1/forecast/digest`: one month, with the running periods, where the planets stand and the dated events. It lists all sign changes, plus the conjunctions of Mars, Jupiter, Saturn, Rahu and Ketu with natal points. - `/v1/forecast/solar-return`: the minute the Sun returns to its birth longitude, with the chart for that minute. `frame: tropical` changes the moment only. The chart stays sidereal on the Lahiri ayanamsa. ## How it was checked - Saturn's move into Pisces on 29 March 2025 and into Aries on 3 June 2027, against [published dates](https://hindupad.com/saturn-transit/), in IST. - Jupiter's move into Gemini against [Amar Ujala's 22:32 IST on 14 May 2025](https://www.amarujala.com/photo-gallery/spirituality/religion/guru-gochar-2025-know-date-time-auspicious-effects-on-zodiac-signs-jupiter-transit-2025-05-14). Ours is 22:41 IST. Almanacs differ by minutes, because they use different ayanamsa and node settings. - The tropical solar return within 2 minutes of the ephemeris library's own `SearchSunLongitude`. - Antardasha lengths in proportion to the Vimshottari years, with no gaps. Times are UTC, to the minute. Sade Sati and Dhaiya are read from the natal Moon's sign. Each period runs from Saturn's first entry to its last exit, joining any returns over a sign boundary. ## Language Set `options.lang` to `hi` for Hindi summaries. # Mobile apps Source: https://developers.astrologics.in/docs/mobile-apps A secret key (test or live) inside an app can be extracted in minutes. Keep it on your server: 1. Your app sends the birth details to **your** backend. 2. Your backend calls the AstroLogics API with the secret key and returns what the app needs. For read-only operations that carry no birth data (panchang, horoscopes, transits), a **publishable key** locked to your domains can be used from a web page. See [authentication](/docs/authentication). For a worked example, see the [Flutter tutorial](/docs/tutorial-flutter). # Widgets Source: https://developers.astrologics.in/docs/widgets One script gives you five elements. They inherit nothing from your page's styles, and you can recolour them. ```html ``` | Element | Shows | Needs | |---|---|---| | `astrologics-panchang` | Today's tithi, nakshatra, yoga, sunrise and Rahu kaal | `key` or `endpoint` | | `astrologics-horoscope` | One sign's reading and scores. Leave out `sign` to let visitors choose | `key` or `endpoint` | | `astrologics-kundli` | A birth form, then lagna and planets | `endpoint` | | `astrologics-match` | Two birth forms, then the Ashtakoot score | `endpoint` | | `astrologics-vastu` | Plot size and direction, then findings | `endpoint` | ## Publishable key or your own server A [publishable key](/docs/authentication) works in the browser, but only for operations that carry no birth data and only on the domains you list for it. So the kundli, matching and Vastu widgets need `endpoint`: the address of a server of yours that holds the secret key. The [WordPress plugin](/docs/wordpress) is one ready-made server. Your server answers these routes under `endpoint`, each passing the API's JSON through: | Route | Calls | |---|---| | `GET /panchang` | `GET /v1/panchang` | | `GET /horoscope/{sign}` | `GET /v1/horoscope/{sign}` | | `GET /places?q=` | `GET /v1/places/search` | | `POST /kundli` | `POST /v1/kundli` | | `POST /match` | `POST /v1/match/ashtakoot` | | `POST /vastu` | `POST /v1/vastu/plot` | | `POST /report/{kundli,match,vastu}` | The [PDF reports](/docs/reports), adding your `brand`. Only with `data-report` on the element | Each visitor's call spends your credits, so limit calls per visitor on your server. Do not log birth details. ## Language and colours Set `lang="hi"` for Hindi. Labels, signs, and panchang, horoscope and Vastu text are Hindi. In the kundli and matching results, planet and nakshatra names and matching notes stay in English. ```css astrologics-kundli { --astro-accent: #1f4e79; --astro-font: Georgia, serif; --astro-radius: 4px; } ``` You can also set `--astro-ink`, `--astro-muted`, `--astro-bg` and `--astro-rule`. On a store: see the [Shopify guide](/docs/shopify) and the [WordPress plugin](/docs/wordpress). # Build an AI astrology chatbot Source: https://developers.astrologics.in/docs/ai-chatbot A language model can talk about a kundli, but it cannot calculate one: asked for a planet's position, it will produce a plausible number that is wrong. The fix is to let the model call the API for every fact, and only explain what the API returns. ## Two ways to connect | | MCP | Tool calling from your server | |---|---|---| | Good for | An assistant or agent that supports MCP | Your own chat product, with your own users | | Setup | Add our MCP server, see [MCP servers](/docs/mcp) | Describe a few operations as tools, and call the API when the model asks | | The key | In the MCP client's config | Only on your server | With MCP, every public operation is a tool, and the model can also search these docs over the docs MCP server. ## Tool calling from your server Give the model a few tools, each one an operation, with its parameters from the [OpenAPI spec](/reference/openapi.yaml). Start small: POST /v1/kundli (2 credits), POST /v1/dasha/vimshottari/current (2 credits), GET /v1/panchang (1 credit) and POST /v1/match/ashtakoot (1 credit) answer most questions. When the model calls a tool, your server makes the request and hands back the JSON: ```js // Your server: the model asked for a kundli. The key never reaches the browser. async function getKundli(birth) { const res = await fetch('https://api.astrologics.in/v1/kundli', { method: 'POST', headers: { Authorization: `Bearer ${process.env.ASTROLOGICS_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ birth }), }); const body = await res.json(); if (!res.ok) return { error: body.error.code, message: body.error.message }; // let the model ask the user again return body.data; } ``` Pass errors back to the model as they are. A `place_ambiguous` error carries `candidates`, so the model can ask the user which place they meant; see [errors](/docs/errors). ## Rules for the model Put these in its instructions: - Use the tools for every position, period, date and score. Never estimate one. - If the birth time is not known, say so, and send `time_accuracy: "unknown"` rather than a guessed time. - Say which method a result follows when it matters, for example the Lahiri ayanamsa or the Ashtakoot table; see [conventions](/docs/conventions). - Present results as what the tradition says, not as certainty or as medical, legal or financial advice. See the [disclaimer](/legal/disclaimer). ## Keys, costs and data - **Keys.** Keep the secret key on your server. A chatbot running in a browser or a phone must call your server, not us. See [mobile apps](/docs/mobile-apps). - **Costs.** Each tool call is an ordinary call, charged its operation's credits; errors are free and test keys are never charged. A chart for one person does not change, so cache it for the conversation instead of asking again. See [caching](/docs/caching-and-data-retention). - **Hindi.** Add `lang=hi` to get labels and readings in Hindi for a Hindi conversation. See [languages](/docs/languages). - **Birth details.** They are your user's personal data. We do not store request bodies; decide what your chatbot keeps, and tell your users. # Languages Source: https://developers.astrologics.in/docs/languages Operations that return text take `lang`: `en` (the default) or `hi` (Hindi, Devanagari). Machine ids such as `"moon"`, `"bharani"` or `"leo"` stay in English in every language, so your code never depends on the language; labels and readings are localised. Fields that explain a method rather than a result, such as `rule` and `source`, stay in English. More Indian languages will follow demand. # MCP servers Source: https://developers.astrologics.in/docs/mcp We run two MCP servers over Streamable HTTP. | Server | Address | Key | What it does | |---|---|---|---| | API | `https://api.astrologics.in/mcp` | Your API key | Every public operation as a tool | | Docs | `https://developers.astrologics.in/mcp` | None | Search the docs, read a page, look up an operation | ## How API tools are charged An MCP call goes through the same checks as a REST call: the same key, rate limits and credits. Only successful calls on a live key are charged, and a test key is never charged. Arguments are treated like any request body: they are [never written](/docs/caching-and-data-retention) to our database or logs. Start with a test key (`al_test_`). Keep keys out of files you commit, because a key in an MCP config is a secret key. ## Set it up Claude Code: claude mcp add --transport http astrologics https://api.astrologics.in/mcp --header "Authorization: Bearer al_test_YOUR_KEY" claude mcp add --transport http astrologics-docs https://developers.astrologics.in/mcp Cursor (`.cursor/mcp.json`): { "mcpServers": { "astrologics": { "url": "https://api.astrologics.in/mcp", "headers": { "Authorization": "Bearer al_test_YOUR_KEY" } }, "astrologics-docs": { "url": "https://developers.astrologics.in/mcp" } } } VS Code (`.vscode/mcp.json`): { "servers": { "astrologics": { "type": "http", "url": "https://api.astrologics.in/mcp", "headers": { "Authorization": "Bearer al_test_YOUR_KEY" } }, "astrologics-docs": { "type": "http", "url": "https://developers.astrologics.in/mcp" } } } ## Fewer tools The API server lists every operation, which is a lot for an agent to hold in mind. To list only some domains, add `?domains=` with the slugs from the [reference](/reference), for example `https://api.astrologics.in/mcp?domains=kundli,dasha`. Add `?compact=1` to spend less of the agent's context: tools come with a one-line summary and no field descriptions, and a call answers with `data` and any `warnings`, without `meta`. It works with `domains`, as in `https://api.astrologics.in/mcp?domains=vastu&compact=1`. # Shopify guide Source: https://developers.astrologics.in/docs/shopify You can show a daily panchang or a horoscope on a Shopify store in a few minutes, with no app and no code beyond one short snippet. > **Early guide:** we have tested the widgets in a browser, but not yet on a real Shopify store. Try this on a page that is not your home page first, and tell us at developers@astrologics.in if anything differs. ## What works this way | Widget | On Shopify | |---|---| | Panchang | Yes, with a publishable key | | Horoscope | Yes, with a publishable key | | Kundli, matching and Vastu | No. They carry birth details or plot details, so they need [a server of your own](/docs/widgets), and a Shopify store does not give you one | There is no AstroLogics app in the Shopify App Store. ## 1. Create a publishable key Open [API keys](/dashboard/keys) and create a **publishable** key. Under allowed origins, list each address your store is reached at, one per line. An origin must match exactly, so include each variant your visitors use: ```text https://your-store.myshopify.com https://www.your-domain.com https://your-domain.com ``` A publishable key is safe in a page because it works only for read-only operations and only from these origins. Never paste a test or live key (`al_test_`, `al_live_`) into a theme: anyone can read it. ## 2. Add a section to your theme 1. In Shopify admin, go to **Online Store**, then **Themes**, and choose **Customize**. 2. Open the page you want, and choose **Add section**, then **Custom Liquid**. 3. Paste one of the snippets below, replacing `YOUR_PUBLISHABLE_KEY`. 4. Save, then open the page on your store's real address to check it. Custom Liquid is available in Online Store 2.0 themes. The theme editor's preview may not count as one of your origins, so if the widget shows a refusal there, check the real page before changing anything. ### Today's panchang Set `lat` and `lon` to the place the panchang is for. Without them, it uses New Delhi. ```html ``` ### A horoscope Leave out `sign` to let visitors choose. Or fix it with, for example, `sign="leo"`, and set `period` to `weekly` for a weekly reading. ```html ``` Two widgets on one page are fine. The script needs to be there only once, and including it twice does no harm. ## Language and colours Add `lang="hi"` to an element for Hindi. If your store has Hindi and English versions, Liquid can follow the visitor's language: ```html ``` Widgets do not inherit your theme's styles. To match your store, set [the colours and font](/docs/widgets#language-and-colours) in a ` ``` ## Credits The widget calls the API from each visitor's browser, so **every page view spends your credits**: 1 for a panchang, and 1 for each horoscope shown. Nothing is cached between visitors. Compare your store's traffic with your [plan](/pricing) before putting a widget on a busy page, and avoid the header, the footer and other parts of the theme that appear on every page. Your plan's rate limit applies too. When a busy page goes over it, or the credits run out, visitors see a short message in place of the reading. The rest of your store is not affected. ## If it shows an error | Message | What to do | |---|---| | The origin is refused (`domain_not_allowed`) | Add the exact address from the browser's address bar to the key's allowed origins | | The key is refused (`invalid_api_key`) | Check that you pasted the whole `al_pub_` key and that it is not revoked | | Too many requests | The page is over your plan's limit. Put the widget on a quieter page, or use a higher plan | ## Your visitors' privacy These two widgets send no birth details. The script sets no cookies, and the browser's request reaches our servers as any request does, with the visitor's IP address. See [caching and data retention](/docs/caching-and-data-retention), and mention the widget in your store's privacy policy. Next: [widgets](/docs/widgets) · [authentication](/docs/authentication) · [WordPress plugin](/docs/wordpress) # Western Source: https://developers.astrologics.in/docs/western These operations return tropical positions of date: apparent longitudes on the ecliptic of that moment. They use the same ephemeris as the rest of the API, which is compared with JPL Horizons in [Accuracy](/docs/accuracy). The bodies are the Sun to Pluto and the true lunar node. Chiron and the asteroids are not included. ## Houses `house_system` can be `placidus` (the default), `equal`, `whole_sign` or `porphyry`. - **Placidus:** a cusp is the ecliptic point whose hour angle is a set fraction of its own semi-arc. Above about 66° of latitude some points never rise or set, so Placidus is not defined there. We return an error that names the alternatives, and do not silently change the system. - **Porphyry:** each quadrant between the angles is split into three equal arcs. - **Equal:** each cusp is 30° on from the ascendant. - **Whole sign:** each house is one sign, starting from the ascendant's sign. With an unknown birth time, `angles`, `houses` and each planet's `house` are `null`. The chart is read at noon, so the Moon can be up to about 6° off. ## Dignities Domicile, exaltation, detriment and fall follow Ptolemy's scheme for the seven classical planets. Uranus, Neptune, Pluto and the nodes have none, because the modern rulerships are not agreed. ## Aspects and orbs Orbs differ between schools, so these are our defaults, and the response states them. | Aspect | Angle | Default orb | |---|---|---| | Conjunction, opposition, trine | 0°, 180°, 120° | 8° | | Square | 90° | 7° | | Sextile | 60° | 5° | | Quincunx | 150° | 3° | | Semisextile, semisquare, sesquiquadrate, quintile, biquintile | 30°, 45°, 135°, 72°, 144° | 2° | A major aspect with the Sun or Moon gets 2° more. Pass `orbs` to use your own, which also removes that extra. An aspect is `applying` when the gap from exact is closing. ## Methods that are choices - **Composite:** each point is the midpoint of the shorter arc between the two charts, and each cusp likewise. The other common method, the Davison chart, is not offered. - **Progressions:** one day after birth for each year of life, using a year of 365.2422 days. The midheaven moves by the solar arc, and the ascendant follows from it at the birth latitude. - **Returns:** the chart for the minute the Sun or Moon is back at its birth longitude, tropically. Give `place` for a relocated return. The Forecast tag has a [sidereal solar return](/docs/forecast). ## How it was checked - Jupiter and Saturn at 0°29′ Aquarius at the great conjunction of 21 December 2020, against the published position. - The Sun at 0°, 90°, 180° and 270° at the equinoxes and solstices that the ephemeris library's `Seasons` search finds. - The ascendant on the eastern horizon and the midheaven on the meridian, using the library's own horizon calculation, at four latitudes on both sides of the equator. - Every Placidus, Porphyry and equal cusp against its definition, typed separately in the tests. - Solar returns against the library's `SearchSunLongitude`. - All 576 house cusps of 12 made-up charts, in Placidus, Porphyry, equal and whole sign, against Swiss Ephemeris 2.10.03. The largest difference was under 0.01 of an arcminute, which is our rounding. The charts run from 1933 to 2045, between 64° north and 55° south. ## Language Set `options.lang` to `hi` for Hindi planet and sign names. The ids stay in English. # WordPress plugin Source: https://developers.astrologics.in/docs/wordpress The plugin adds the five [widgets](/docs/widgets) to WordPress and does the server's job for you, so no code is needed. [Download the plugin](/downloads/astrologics-wordpress.zip) > **Early version:** we have tested the plugin's server code against a stand-in for WordPress, and the widgets in a browser. It has not yet run on a live WordPress site, so try it on a staging site first. ## Set it up 1. In WordPress, go to Plugins, Add New, Upload Plugin, and choose the zip. 2. Activate it, then open Settings, AstroLogics. 3. Paste a secret API key from your [dashboard](/dashboard). 4. Add a block from the AstroLogics group, or a shortcode, to any page. ## Shortcodes ```text [astrologics_panchang lat="28.6139" lon="77.209"] [astrologics_horoscope sign="leo" period="weekly"] [astrologics_kundli] [astrologics_match] [astrologics_vastu] ``` Each also takes `lang="hi"`. Without it, the site's language from the settings page applies. ## Credits and limits Visitors' calls spend your credits. Panchang, horoscope and place search results are cached for an hour, which saves credits. Each visitor's address may cause 60 calls an hour. ## PDF reports Turn on **Let visitors download a PDF** to add a download button, with your name, contact and colour from the settings page. Each PDF spends 10 credits and the page has no payment step, so leave it off unless you are happy to cover that. ## Your visitors' details Birth details go from your site to our API to get the answer. The plugin does not save them, and [we do not keep them](/docs/caching-and-data-retention). Mention this in your own privacy policy, because your visitors are sending data through your site to ours. # Chinese Source: https://developers.astrologics.in/docs/chinese These operations measure the Sun and Moon directly and do not read a stored table. They return the structure of a chart and leave the reading to you. ## The four pillars - **Year:** it turns at Li Chun, the moment the Sun reaches 315°, not at Lunar New Year. - **Month:** it turns at each jie, every 30° of the Sun from Li Chun. The stem follows the Five Tigers rule. - **Day:** it counts on the sixty-day cycle. 1 October 1949 is Jia Zi. - **Hour:** there are twelve double hours, starting at 23:00. The stem follows the Five Rats rule. Each pillar returns its hidden stems, ten gods relative to the day master, and nayin. `elements` counts the visible stems and branches separately from the hidden stems. We don't return day-master strength, useful gods or a reading, because schools disagree on them and they need interpretation that we have not had reviewed. ## Conventions you choose | Option | Values | Effect | |---|---|---| | `time_basis` | `clock` (default), `true_solar` | True solar time corrects for longitude and the equation of time. It changes the hour pillar, and sometimes the day. | | `zi_convention` | `day_changes_at_23` (default), `late_zi` | From 23:00, the first moves the day pillar to the next day. The second keeps the day and takes only the hour stem from the next day. | These defaults are our choice, and schools differ. The response states which were used. Compare results from another calculator only with the same settings. ## Luck pillars The direction is forward for a male born in a yang-stem year or a female born in a yin-stem year, and backward otherwise. This is the traditional rule, and it needs `gender`, which we use for the response and do not store. Each three days from birth to the jie count as one year of the starting age. ## Calendar Month 11 holds the winter solstice. Months start on the day of the new moon in China's time, which is UTC+8 from 1929 and Beijing mean time before. When 13 months fall between two months 11, the first one without a zhongqi is the leap month. Dates run from 1901 to 2100. `/v1/chinese/zodiac` returns the birth animal by both Li Chun and Lunar New Year, because people born between the two get different answers. ## Relations `/v1/chinese/compatibility` and `/v1/chinese/annual` list six harmonies, three harmonies, clashes, harm, punishment, destruction, and stem combinations and clashes. Compatibility counts the harmonies and conflicts on the year and day pillars. It gives no percentage, because the classical rules do not give one. Which pillars to compare is our choice, so the response labels it a convention. ## How it was checked - Chinese New Year on all 31 dates from 2000 to 2030, against [Wikibooks' list](https://en.wikibooks.org/wiki/Ba_Zi/Chinese_New_Year). For 2030 that list says 2 February, while [other calendars](https://www.calendardate.com/chinese_new_year_2030.htm) and our calculation say 3 February. - Leap months in 2017 and 2020, as [Wikipedia's Chinese calendar article](https://en.wikipedia.org/wiki/Chinese_calendar) names them. - The day cycle against [Wikipedia's worked example](https://en.wikipedia.org/wiki/Sexagenary_cycle), and the year pillars against its table. - Solar terms at the equinoxes and solstices against the ephemeris library's `Seasons`. - The Five Tigers and Five Rats rules, ten gods and relations, typed separately in the tests. The hidden stems and nayin tables are the common ones, but we have not checked them against a named classical edition. ## Language Set `options.lang` to `hi` for Hindi animal and element names. Stems, branches, ten gods and nayin stay in Chinese and English. # n8n guide Source: https://developers.astrologics.in/docs/n8n [n8n](https://n8n.io) is a tool for building automations from connected steps. There is no AstroLogics node for it, and you do not need one: its **HTTP Request** node can call every operation in the [API reference](/reference). We imported and ran both workflows below in n8n 2.45.7, against a stand-in server that returned our documented example responses. They have not yet run against a live key. If yours behaves differently, tell us at developers@astrologics.in. ## 1. Save your key as a credential Keep your key in an n8n credential, not in a node, so it is never included when you share or export a workflow. 1. Create a key on the [API keys](/dashboard/keys) page. A test key (`al_test_`) is free to try with and is never charged. 2. In n8n, open **Credentials** and create a **Header Auth** credential. 3. Set **Name** to `Authorization`, and **Value** to `Bearer` followed by a space and your key. 4. Save it as `AstroLogics API key`. ## 2. Import a workflow Download a file, then in a new n8n workflow open the menu at the top right and choose **Import from File**. | Workflow | What it does | Credits for each run | |---|---|---| | [Daily panchang](/downloads/n8n/astrologics-daily-panchang.json) | Each morning at 6:00, gets the day's panchang and writes one line of text | 1 | | [Daily horoscope on WhatsApp](/downloads/n8n/astrologics-daily-horoscope-whatsapp.json) | Each morning at 7:00, gets one sign's reading and sends it through AiSensy. See the [WhatsApp guide](/docs/whatsapp) first | 1 | After importing: 1. Open each HTTP Request node and choose your credential. An imported workflow does not carry one. 2. Change the values in the **Settings** node. 3. Choose **Execute workflow** to run it once by hand, and check each step's output. 4. Turn the workflow on, so that the schedule runs it. Both start switched off. The daily panchang ends with a line of text in a field named `message`, like this: ```text 2026-10-02: Saptami, Mrigashira. Rahu kaal 10:41 to 12:10. ``` Connect any n8n step after it to send that line on, such as email, Telegram or Slack. ## 3. Call any other operation Add an **HTTP Request** node and fill it in from the operation's page in the [API reference](/reference): | Field | Value | |---|---| | Method | The operation's method | | URL | `https://api.astrologics.in`, then the operation's path | | Authentication | Generic Credential Type, then Header Auth, then `AstroLogics API key` | | Query parameters | Those listed for the operation | | Body | For POST operations, JSON as shown in the operation's example | The response is always `data`, `meta` and `warnings`, so later steps read values such as `{{ $json.data.tithi.label }}`. ## Birth details and your n8n history We never store request bodies. n8n is separate: it can save the input and output of every run, and that would include any birth details your workflow handles. Both workflows here are set not to save successful runs, but a failed run is still saved. If you add a step that handles a client's birth details, send them in a POST body, and check **Settings** for the workflow, including what it saves when a run fails. See [caching and data retention](/docs/caching-and-data-retention). ## When a call fails The HTTP Request node stops the workflow on an error response. The body holds the code and the message, listed in [errors](/docs/errors). For a run on a schedule, set an error workflow in the workflow's settings, so that you hear about it. A call that returns `429` has reached your [rate limit](/docs/rate-limits). In the node's settings, turn on **Retry On Fail**, with a wait between tries. # Feng Shui Source: https://developers.astrologics.in/docs/feng-shui These operations count on the Luo Shu from the year and a compass bearing. They say where the traditional stars fall. They give no cures or advice, because those vary by practitioner and we have not had any reviewed. Feng Shui is a tradition, and these results are not a measure of how a building performs. ## Kua and Eight Mansions The digits of the year are summed down to one digit. A male's number is 11 minus that digit, and a female's is that digit plus 4, each reduced to one digit. A 5 becomes 2 for a male and 8 for a female. Some sites stop at 5. The year turns at Li Chun by default. Some practitioners use Lunar New Year, so `year_boundary` lets you choose, and `boundaries_agree` says when it makes no difference. The traditional formula needs `gender`, which we use for the response and do not store. `/v1/feng-shui/house` gives a building the gua of the palace it sits in. Pass an occupant's `kua` to see which of their mansions the front and back fall in. The English and Hindi mansion names are translations, and other books use other words, so rely on the `id`. ## Flying stars Pass the facing bearing and either `period` or `built_year`. Periods last 20 years, and Period 9 runs from Li Chun 2024 to Li Chun 2044. `built_year` can't tell which side of Li Chun a building was finished, so pass `period` for buildings finished in a period's first weeks. - **Base stars:** the period star at the center, flying forward along the Luo Shu path. - **Mountain and water stars:** the base stars at the sitting and facing palaces move to the center. Each flies forward or in reverse according to the polarity of the sitting or facing mountain, taken at the same position in that star's home palace. A 5 takes the polarity of the period star's palace. `structure` names the chart when the period star stands in a recognised place: `wang_shan_wang_xiang`, `shang_shan_xia_shui`, `double_at_facing` or `double_at_sitting`. `timeliness` is `current` for the period star, `next` and `future` for the two after it, `retreating` for the one before, and `past` otherwise. That grouping is a simplification, and schools vary. We do **not** calculate replacement charts (ti gua), because schools disagree on when they apply. `near_boundary` is `true` within 3° of a mountain's edge, where a practitioner might use one or re-measure. `replacement_chart` is always `false`. ## Annual and monthly stars The year's center star comes from the digits of the year, and runs from Li Chun to Li Chun. The first month's star is 8, 5 or 2 according to the year's branch, and falls by one each month. Tai Sui is the year's branch, Sui Po is opposite it, and San Sha follows the three-harmony group of the branch. Months start at the jie, and `/v1/chinese/annual` gives their dates. ## How it was checked Sources are practitioner websites, not classical texts. - Three whole charts, star for star: [Period 8 S2](https://www.skillon.com/feng-shui-calculator.cfm/period/8/facing/2/period-8-facing-S2), [Period 8 SW1](https://www.skillon.com/feng-shui-calculator.cfm/period/8/facing/4/period-8-facing-SW1) and [Period 9 N2](https://www.skillon.com/feng-shui-calculator.cfm/period/9/facing/14/period-9-facing-N2). Skillon labels the SW1 chart "Up Water Up Mountain". Its 8s stand at the sitting and facing, which is the prosperous arrangement, so we return `wang_shan_wang_xiang`, and [fengshuied.com](https://www.fengshuied.com/?p=774) names the matching chart that way. - The Five Yellow, Tai Sui, Sui Po and San Sha for 2025 and 2026, and the month centers for 2026, against [Master Sean Chan's charts](https://www.masterseanchan.com/fengshui-2026-flying-star-chart/), plus [one published month chart](https://www.wofs.com/?p=23088). - Ten published Kua examples, and the [Eight Mansions table](https://www.fengshuied.com/?p=23), which a [second site](https://www.masterseanchan.com/feng-shui-bed-direction/) matches. - The 24 mountains against [published degrees](https://www.fengshuied.com/?p=89). Some calculators start each range 0.1° later. Bearings are compass readings, so check for magnetic interference on site. ## Language Set `options.lang` to `hi` for Hindi direction and mansion names. Star numbers and ids don't change. # WhatsApp guide Source: https://developers.astrologics.in/docs/whatsapp AstroLogics does not send WhatsApp messages. Your server or automation gets the reading from our API, then gives it to a WhatsApp Business Solution Provider, which delivers it. You keep your subscribers' phone numbers and consent with that provider and on your side. **Phone numbers never need to reach AstroLogics**, because a horoscope call carries only the sign, the period, the date and the language. > **Early guide:** we checked each provider's request against its own documentation on 3 November 2026, and we ran the AiSensy workflow below against a stand-in server. We have not sent a real message through any of these providers. Check their current documentation before you rely on the details, and tell us at developers@astrologics.in if anything differs. ## Before you start - **A WhatsApp Business API account** with a provider. A personal or ordinary WhatsApp Business app number will not do. - **An opt-in from each person you message.** Keep a record of it, and make it easy to stop. This is WhatsApp's rule, and your responsibility. - **An approved template.** To message someone who has not written to you in the past 24 hours, you must use a template that Meta has approved. - **A cost in mind.** Meta charges per template message, by category, and your provider may add its own charge. A regular horoscope is likely to count as marketing, the dearer category. Meta decides the category when it reviews your template, so check your provider's current rates. ## 1. Create a template Your provider's dashboard submits it for approval. This one has three variables: ```text Namaste {{1}}. Your {{2}} reading for today: {{3}} Reply STOP to stop these messages. ``` Variable values cannot contain line breaks. Our `reading` field is a single line. Meta tends to refuse a template that starts or ends with a variable, which is why this one has words on both ends. Keep the Hindi and English versions as two templates, each in its own language. ## 2. Get the reading once for each sign Readings are the same for everyone with the same sign, period, date and language. Fetch each once a day, however many subscribers you have, and reuse it. That is at most 12 calls a day for each language, at 1 credit each. 
curl 'https://api.astrologics.in/v1/horoscope/leo?period=weekly&date=2026-10-02&lang=hi' \
  -H 'Authorization: Bearer al_test_YOUR_KEY'
Use `data.sign_label` for `{{2}}` and `data.reading` for `{{3}}`. With `lang=hi` both are in Hindi. ## 3. Send it through your provider Providers are in alphabetical order. We know of no neutral ranking, so choose on price, support and what your business already uses. | Provider | Good to know | |---|---| | [AiSensy](#aisensy) | You send through a campaign you create in its dashboard | | [Gupshup](#gupshup) | Takes a form post, and identifies a template by its ID | | [Interakt](#interakt) | Its public API is not on its Starter plan | | [LeadNXT](#leadnxt) | Offers a WhatsApp Business API. We found no public API documentation | | [WATI](#wati) | A request needs your tenant ID, and a success means accepted, not delivered | The values in these requests are made up. Each provider's key is a secret, so send these from a server or from n8n, never from a web page. ### AiSensy Create the template, then an API campaign that uses it, and set the campaign to Live. Your API key is in the dashboard. See [AiSensy's API reference](https://wiki.aisensy.com/en/articles/11501889-api-reference-docs). ```bash curl -X POST https://backend.aisensy.com/campaign/t1/api/v2 \ -H "Content-Type: application/json" \ -d '{ "apiKey": "YOUR_AISENSY_KEY", "campaignName": "daily_horoscope", "destination": "+910000000000", "userName": "Your AiSensy project name", "templateParams": ["Asha", "Leo", "A good day to finish what you started."] }' ``` The `templateParams` list must have as many values as the template has variables, or AiSensy rejects the request. There is an n8n workflow for this one: [Daily horoscope on WhatsApp](/downloads/n8n/astrologics-daily-horoscope-whatsapp.json). Follow the [n8n guide](/docs/n8n), and for the AiSensy step create a **Custom Auth** credential, so that your key is not stored in the workflow: ```json { "body": { "apiKey": "YOUR_AISENSY_KEY" } } ``` ### Gupshup A template is identified by its ID, which you get from Gupshup once it is created. `source` is your registered number, and neither number has a `+`. See [Gupshup's template messages](https://docs.gupshup.io/docs/template-messages). ```bash curl -X POST https://api.gupshup.io/wa/api/v1/template/msg \ -H "apikey: YOUR_GUPSHUP_KEY" \ --data-urlencode "source=910000000001" \ --data-urlencode "destination=910000000000" \ --data-urlencode 'template={"id":"YOUR_TEMPLATE_ID","params":["Asha","Leo","A good day to finish what you started."]}' ``` A success means that Gupshup has accepted the message. Whether it was delivered comes to your webhook. ### Interakt Your key is in the dashboard under Developer Settings, and is sent after the word `Basic`, as it is. The template's language must match the one you created it in. See [Interakt's guide](https://www.interakt.shop/resource-center/how-to-send-whatsapp-templates-using-apis-webhooks). ```bash curl -X POST https://api.interakt.ai/v1/public/message/ \ -H "Authorization: Basic YOUR_INTERAKT_KEY" \ -H "Content-Type: application/json" \ -d '{ "countryCode": "+91", "phoneNumber": "0000000000", "type": "Template", "template": { "name": "daily_horoscope", "languageCode": "en", "bodyValues": ["Asha", "Leo", "A good day to finish what you started."] } }' ``` ### LeadNXT [LeadNXT](https://www.leadnxt.com/whatsapp-business-api-ai-chatbot/) offers bulk WhatsApp campaigns, a chatbot and missed-call-to-WhatsApp, along with its lead management tools. We did not find public API documentation, so ask LeadNXT how to send a template by API. The horoscope call in step 2 stays the same. ### WATI Your tenant ID and token are in the dashboard under API Settings. WATI recommends its newer v3 API for new work, so check [its reference](https://docs.wati.io/v2.5/reference/sendtemplatemessage) first. This is the documented v1 request: ```bash curl -X POST "https://live-mt-server.wati.io/YOUR_TENANT_ID/api/v1/sendTemplateMessage?whatsappNumber=910000000000" \ -H "Authorization: Bearer YOUR_WATI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "template_name": "daily_horoscope", "broadcast_name": "daily_horoscope", "channel_number": "910000000001", "parameters": [ { "name": "1", "value": "Asha" }, { "name": "2", "value": "Leo" }, { "name": "3", "value": "A good day to finish what you started." } ] }' ``` ## Other messages The [panchang](/reference/panchang-and-muhurat#getPanchang) works the same way, at 1 credit for each date and place. It returns no paragraph of text, so build your line from `data.tithi.label`, `data.nakshatra.label` and `data.rahu_kaal`, as the [daily panchang workflow](/docs/n8n) does. Keep to readings that are the same for many people. A message built from one person's birth details is that person's data, so check what your provider stores and keeps before you send it. # Moving from another astrology API Source: https://developers.astrologics.in/docs/migrating Two astrology APIs can both be correct and still disagree, because each chooses an ayanamsa, a house system, a sunrise and a matching table. Most differences you will see after a move come from those choices, not from errors. Check them first, then compare the results side by side with a test key, which is never charged. ## 1. Settle the conventions
engine_version
2026.10.10
ayanamsa
lahiri
kp_ayanamsa
kp_new (Lahiri − 5′24″)
house_system
whole_sign
node
true
sunrise
upper limb, refracted
moonrise
the Moon's centre on the true horizon (festival moments; the panchang does not give moonrise)
lunar_month
amanta (new moon to new moon); purnimanta names alongside
ayanamsa_options
lahiri (default), raman, krishnamurti, yukteshwar, fagan_bradley: options.ayanamsa on chart operations; the calendar, panchang and KP are unaffected
not_computed
moonrise in the panchang, yoga/karana end times, Vaishnava paran (Ekadashi), Vaishnava Janmashtami, Ghatak Chakra, Chara-dasha antardashas
The [conventions](/docs/conventions) page explains each one. The ones that most often explain a difference: - **Ayanamsa.** Ours is Lahiri by default. If your old API used another, pass `options.ayanamsa` on chart operations (`raman`, `krishnamurti`, `yukteshwar` or `fagan_bradley`) to match it while you compare. - **Houses.** Ours are whole-sign houses from the lagna. An API using Sripati or Placidus houses for Vedic charts will place some planets in a different house; our POST /v1/kundli/bhav-chalit (1 credit) gives the Sripati bhavas. - **Node.** Ours is the true node. A mean node differs from it by up to about 1.7°. - **Sunrise.** Ours is the upper limb of the Sun, with refraction. A centre-of-disc sunrise is a few minutes later, which can change the vara, Rahu Kaal and choghadiya near their edges. ## 2. Send the birth the same way - **Time and place.** Send the local birth time and the place. We work out the timezone in force at that date, including India's offsets before 1947 (see [historical timezones](/blog/historical-timezones-in-birth-charts)). If your old API took a fixed offset such as `+05:30`, an older birth can move by an hour; send `timezone` to match it while you compare. See [birth input](/docs/birth-input). - **An unknown time.** Old APIs often fill in noon. We do not: set `time_accuracy` to `unknown` and the fields that depend on it are left out and listed in `warnings`. ## 3. Map the operations Look up each call you make today in the [reference](/reference) or in the [glossary](/glossary), which names the operation for each term. Several chart calls can be made at once with POST /v1/kundli/bundle (3 credits). ## 4. Compare side by side 1. Pick some made-up births that cover your users: different decades, places and times of day. 2. Call both APIs, and ours with a test key. 3. Compare the planets' longitudes first. They should agree closely once the ayanamsa and node match; see [accuracy](/docs/accuracy) for ours against NASA JPL Horizons. 4. Then compare what is built on them: houses, nakshatras, dasha dates, matching scores. A difference there usually traces back to a convention above. ## Kundli matching scores Ashtakoot tables differ between published sources, so two APIs can give different totals for the same couple. Ours uses one published table for each koota, named on [conventions](/docs/conventions#ashtakoot-tables), so a score can be checked by hand. ## When you are ready Switch your server to a live key (`al_live_`). Nothing else changes: the same calls, the same results. If you find a difference you cannot explain, write to us at developers@astrologics.in with the `request_id` and the input. # Notes for coding agents Vedic astrology API over HTTPS. Base URL `https://api.astrologics.in`. The contract is OpenAPI 3.1: https://developers.astrologics.in/reference/openapi.yaml. Every docs page is also markdown: https://developers.astrologics.in/llms.txt lists them. ## Keys Send `Authorization: Bearer ` on every request. - `al_test_`: the real engine, never charged; `meta.mode` is `test`. Start here. - `al_live_`: spends the plan's credits. Only successful (2xx) calls are charged. - `al_pub_`: for widgets in the browser only: read-only operations without birth data, from the origins listed on the key. - Test and live keys are secret. Use them only from a server, never in a web page or a mobile app; see https://developers.astrologics.in/docs/mobile-apps.md. ## Request Birth details: https://developers.astrologics.in/docs/birth-input.md. A place is coordinates, a `place_id` from `GET /v1/places/search`, or a free-text query. Do not invent a birth time: set `time_accuracy`. Use made-up birth details in tests and examples. `POST /v1/kundli`: ```json { "birth": { "date": "1990-08-13", "time": "06:30", "place": { "latitude": 28.6139, "longitude": 77.209 } } } ``` ## Errors Read `error.code`, not the message: https://developers.astrologics.in/docs/errors.md. Errors are never charged. - `error.issues` lists every problem in the request at once; fix them together. - `place_ambiguous` comes with `error.candidates`: send one of their `place_id` values. - A `404` for an unknown path can carry `error.suggestions`: the operations you may have meant. - A `429` carries `Retry-After`: `rate_limited` means wait and retry; `quota_exhausted` means retrying soon will not help. - Quote `request_id` when reporting a problem. ## SDKs Official clients for TypeScript and JavaScript, Python and PHP, downloaded from us for now: https://developers.astrologics.in/products/sdks.md. Quickstarts: https://developers.astrologics.in/docs/quickstart-typescript.md, https://developers.astrologics.in/docs/quickstart-python.md, https://developers.astrologics.in/docs/quickstart-php.md. ## MCP Every public operation is a tool at `https://api.astrologics.in/mcp` (your API key), and the docs are searchable at `https://developers.astrologics.in/mcp` (no key). Setup: https://developers.astrologics.in/docs/mcp.md. ## Credits and storing results Each operation's credits are in the reference; each response reports the balance in `X-Credits-Remaining`. Rate limits: https://developers.astrologics.in/docs/rate-limits.md. What to cache: https://developers.astrologics.in/docs/caching-and-data-retention.md. Calculation changes are versioned by `meta.engine_version`: https://developers.astrologics.in/docs/versioning-and-calculation-changes.md. ## Operations - [Places & time](https://developers.astrologics.in/reference/places-and-time.md): 4 operations - [Kundli](https://developers.astrologics.in/reference/kundli.md): 24 operations - [Dasha](https://developers.astrologics.in/reference/dasha.md): 4 operations - [Doshas](https://developers.astrologics.in/reference/doshas.md): 4 operations - [Matchmaking](https://developers.astrologics.in/reference/matchmaking.md): 4 operations - [Panchang & muhurat](https://developers.astrologics.in/reference/panchang-and-muhurat.md): 10 operations - [Calendar](https://developers.astrologics.in/reference/calendar.md): 3 operations - [Horoscopes](https://developers.astrologics.in/reference/horoscopes.md): 4 operations - [Transits](https://developers.astrologics.in/reference/transits.md): 6 operations - [Timing](https://developers.astrologics.in/reference/timing.md): 5 operations - [Numerology](https://developers.astrologics.in/reference/numerology.md): 8 operations - [Chart images](https://developers.astrologics.in/reference/chart-images.md): 2 operations - [Reports](https://developers.astrologics.in/reference/reports.md): 3 operations - [KP](https://developers.astrologics.in/reference/kp.md): 6 operations - [Lal Kitab](https://developers.astrologics.in/reference/lal-kitab.md): 4 operations - [Annual](https://developers.astrologics.in/reference/annual.md): 1 operation - [Biorhythm](https://developers.astrologics.in/reference/biorhythm.md): 6 operations - [Forecast](https://developers.astrologics.in/reference/forecast.md): 5 operations - [Western](https://developers.astrologics.in/reference/western.md): 9 operations - [Chinese](https://developers.astrologics.in/reference/chinese.md): 7 operations - [Feng Shui](https://developers.astrologics.in/reference/feng-shui.md): 5 operations - [Vastu](https://developers.astrologics.in/reference/vastu.md): 7 operations - [Platform](https://developers.astrologics.in/reference/platform.md): 2 operations