Recipe-driven · 20 named recipes · AR/VR walkthrough

Vastu API Integration Guide

Everything you need to integrate Vedic compliance into your AR/VR scanner, proptech listing, interior-design tool, or chatbot. Curl + JavaScript + Python for every endpoint, with full multilingual examples and a clear "which endpoint for which job" decision tree.

Two Integration Paths

Both are LIVE. You can mix freely — the most powerful integrations use both.

A. AI Query (natural language)

Send a free-text Vastu question. Receive a written answer with classical citations in 22 languages.

Endpoint: POST /api/v1/query

Best for: chatbots, voice assistants, content surfaces, free-form input.

B. REST Endpoints (structured data)

Send structured input (rooms, polygons, bearings). Receive deterministic JSON with score, defects, mandala coords.

Namespace: /v2/astrology/vastu/* (18 endpoints LIVE: 16 Tier 1 + 2 Tier 2 partial)

Best for: AR/VR scanners, proptech audits, design tools, dashboards.

Decision Tree — When to Use What

I want to...Use this
Answer a Vastu question someone typedPOST /api/v1/query
Show a 9-cell or 81-cell grid in AR scene/vastu/mandala/project/9-zone or /81-pada
Score an entire floor plan/vastu/audit/floor-plan
Score AND get heatmap AND remediation order/vastu/audit/floor-plan-detailed
Check one (room, zone) pair only/vastu/audit/single-room
Convert phone-compass bearing to true-north/vastu/direction/declination
Convert "north-east" / "ishanya" to a zone/vastu/direction/correct
Map bearing-degree to zone label/vastu/direction/zone-from-bearing
Classify the door's pada (auspicious/avoid)/vastu/entrance/pada
Validate AR scan quality before audit/vastu/ar/scan-quality
Highlight Brahmasthan no-go zone/vastu/mandala/project/brahmasthan
Audit plot length:width ratio/vastu/plot/ratio
Classify plot polygon shape/vastu/plot/shape
Get the 9-zone reference table (cache once)/vastu/reference/mandala/9-zone

Recipes — Per Endpoint

Set VEDIKA_KEY env var to your vk_live_* token. Sandbox alternative at api.vedika.io/sandbox/vastu/* needs no auth.

Recipe 1 — Floor plan audit (curl)
When: User finished tagging rooms; you want score + defect list.
curl -X POST https://api.vedika.io/v2/astrology/vastu/audit/floor-plan \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rooms": [
      { "roomType": "kitchen",        "zone": "SE" },
      { "roomType": "master_bedroom", "zone": "SW" },
      { "roomType": "pooja",          "zone": "NE" },
      { "roomType": "toilet",         "zone": "NE" }
    ]
  }'

→ { "data": { "score": 80, "grade": "B", "totalRooms": 4,
              "prescribedCount": 3,
              "defects": [{ "room": "toilet", "zone": "NE",
                            "severity": "severe",
                            "remedy": "Paint walls white...",
                            "recommendedZone": "NW",
                            "source": "Manasara Shilpashastra Ch. 7.4" }],
              "verified": true }, "billing": {...}, "meta": {...} }
Recipe 2 — Mandala projection (JavaScript)
When: AR app finished a scan and has a plot polygon.
const r = await fetch(
  'https://api.vedika.io/v2/astrology/vastu/mandala/project/9-zone',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VEDIKA_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      plotPolygon: [[0,0], [12,0], [12,12], [0,12]],
      bearingDeg:  45      // true-north corrected
    })
  }
);
const { data } = await r.json();
data.cells.forEach(cell => {
  // cell.polygon is in YOUR world coordinates — render directly
  arScene.addPolygon(cell.polygon, {
    color: cell.zone === 'CENTER' ? 'yellow' : 'green',
    label: cell.zone
  });
});
Recipe 3 — AI Query in Hindi (curl)
When: User typed a Vastu question in their language.
curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "मेरे मुख्य द्वार दक्षिण-पश्चिम मुखी है, क्या उपाय करूं?" }'

→ Hindi answer citing Vastu Ratnavali 3.12, listing 2-3 concrete remedies
  (Hanuman yantra above door, brass pyramid on threshold, etc.).
Recipe 4 — Detailed audit (Python)
When: Premium audit — one call returns score + heatmap + remediation order.
import os, requests
r = requests.post(
    'https://api.vedika.io/v2/astrology/vastu/audit/floor-plan-detailed',
    headers={'Authorization': f'Bearer {os.environ["VEDIKA_KEY"]}'},
    json={
        'rooms': [
            {'roomType': 'kitchen', 'zone': 'SE'},
            {'roomType': 'toilet',  'zone': 'NE'},
        ],
        'plotPolygon': [[0,0],[12,0],[12,12],[0,12]],
        'bearingDeg': 0
    }
).json()

print(r['data']['score'], r['data']['grade'])
for step in r['data']['remediationOrder']:
    print(step['step'], step['room'], '-', step['action'])
# 1 toilet - Paint walls white. Camphor + copper pyramid. Hanuman yantra...
Recipe 5 — Magnetic declination (true-north correction)
When: AR scan starts. Call once per scan to convert phone-compass to true-north.
curl "https://api.vedika.io/v2/astrology/vastu/direction/declination?lat=18.5204&lon=73.8567" \
  -H "Authorization: Bearer $VEDIKA_KEY"

→ { "data": { "declinationDeg": 0.45,
              "interpretation": "Magnetic north is 0.45° EAST of true north — compass over-reads.",
              "gridEpoch": "2025.0",
              "verified": true }, ... }

# Use it:  trueBearing = (compassBearing - 0.45 + 360) % 360
Recipe 6 — 32-pada door classifier
When: User taps the door position in your AR scene.
curl -X POST https://api.vedika.io/v2/astrology/vastu/entrance/pada \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -d '{
    "plotPolygon": [[0,0],[12,0],[12,12],[0,12]],
    "doorXY": [10, 6],
    "bearingDeg": 0
  }'

→ { "data": { "pada": { "index": 11, "deity": "Surya", "quadrant": "E",
                        "auspiciousness": "auspicious",
                        "effect": "Vitality, fame, paternal blessings",
                        "source": "Manasara Ch. 9.12; Brihat Samhita 53.71" } } }
Recipe 7 — AR scan quality (gate before audit)
When: Scan done; verify quality before paying for audit.
curl -X POST https://api.vedika.io/v2/astrology/vastu/ar/scan-quality \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -d '{
    "pointCloudDensity": 1800,
    "polygonClosure": true,
    "compassConfidence": 0.9,
    "gpsConfidence": 0.95,
    "roomsTagged": true,
    "scanDurationSec": 45,
    "scannedAreaM2": 30,
    "roomCount": 4
  }'

→ { "data": { "grade": "A", "score": 92, "acceptForAudit": true,
              "missingData": [], "warnings": [], "reScanSuggestions": [],
              "dimensions": {...} } }
# If acceptForAudit:false, present reScanSuggestions[] in your UI.
Recipe 8 — Plot ratio audit (pre-construction)
When: Real-estate listing or builder's pre-construction audit.
curl -X POST https://api.vedika.io/v2/astrology/vastu/plot/ratio \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -d '{ "plotPolygon": [[0,0],[18,0],[18,9],[0,9]] }'

→ { "data": { "lengthM": 18, "widthM": 9, "ratio": 2.0,
              "category": "borderline", "acceptable": true,
              "remedy": "Plot ratio approaching classical 2:1 limit. Add heavy SW corner..." } }

AI Query — Trigger Modes & Custom Prompts

The AI Query path (POST /api/v1/query) supports three ways to invoke Vastu mode. Use the simplest one that fits your UX.

1. Auto-detection (default — 17 trigger patterns)

Send any natural-language Vastu question. The platform auto-detects intent across English keywords, Sanskrit zone names, and common placement triggers. No special syntax needed — works for 95% of integrations.

curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -d '{ "question": "Where should I put my pooja room?" }'

# Auto-fires on: vastu, vaastu, ishanya, agneya, nairutya, vayavya, brahmasthana,
#                main door, pooja room, kitchen direction, sleeping direction,
#                home faces, bedroom NE/NW/SE/SW, etc.

2. Bracket override — {vastu} / {vaastu}

When the user's wording is ambiguous (e.g. "What about my place?"), prefix or inject a {vastu} bracket token to force-trigger the Vastu directive. Useful when:

# Bracket-prefixed (recommended for explicit control)
curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -d '{ "question": "{vastu} What about my master bedroom?" }'

# Equivalent — bracket anywhere in the question
curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -d '{ "question": "Help with placement {vastu} please" }'

# Both forms ({vastu} and {vaastu}) trigger the same Vastu directive injection.

3. Enterprise custom Vastu directive (Tier 3 roadmap)

Enterprise customers will be able to inject their own additional Vastu directives — for example, region-specific remedy preferences, branded language tone, or custom defect-severity weights. Available via a customDirective field on enterprise API keys (vk_ent_*).

curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_ent_YOUR_KEY" \
  -d '{
    "question": "{vastu} Master bedroom in NE — what should I do?",
    "customDirective": {
      "region": "south-india",
      "preferredRemedies": ["yantra", "color-therapy"],
      "tone": "formal-tamil",
      "additionalRules": [
        "Always recommend Tirupati Balaji yantra for SW kitchens",
        "Cite Manasara over Mayamata when both apply"
      ]
    }
  }'

# Currently: customDirective is accepted but stored only — applied in Tier 3 release (~3 weeks ETA).
# Today: enterprise responses use the same auto-detection + factBlock as standard plans.

Trigger precedence: Bracket override {vastu} always wins. Then auto-detection patterns. Then optional customDirective additions (enterprise only). All three coexist in the same request — they compose, not conflict.

Multilingual AI Query

The AI Query path auto-detects 22 languages. No translation layer required.

LanguageSample question
Hindiमेरे मुख्य द्वार दक्षिण-पश्चिम मुखी है, क्या उपाय करूं?
HinglishBhaiya, mera kitchen south-east mein hai, kya yeh sahi hai?
Bengaliআমার পূজার ঘর কোন দিকে রাখা উচিত?
Tamilநான் தென்மேற்கு வாசலில் வீடு கட்டலாமா?
Teluguనా శయన గది పడమర దిక్కులో ఉంది, ఇది సరియేనా?
Marathiआग्नेय कोनात स्वयंपाकघर का असावे?
Gujaratiમારા ઘરમાં બ્રહ્મસ્થાન ખુલ્લું હોવું જરૂરી છે કે કેમ?
Kannadaನನ್ನ ಮನೆಯ ಮುಖ್ಯ ದ್ವಾರ ಯಾವ ದಿಕ್ಕಿಗೆ ಇರಬೇಕು?

AR/VR Walkthrough — 7 Steps

A complete mobile flow with iPhone ARKit RoomPlan or Android Sceneform.

1App boot — fetch reference data once

Cache the reference table locally.

const zones    = await fetch('/v2/astrology/vastu/reference/mandala/9-zone',  { headers });
const devatas  = await fetch('/v2/astrology/vastu/reference/mandala/45-devatas', { headers });
cacheLocally(zones, devatas);  // pay $0.024 once
2Scan starts — get true-north correction
const decl = await fetch(
  `/v2/astrology/vastu/direction/declination?lat=${lat}&lon=${lon}`,
  { headers }
).then(r => r.json());
const trueBearing = (compassBearing - decl.data.declinationDeg + 360) % 360;
3Scan finishes — extract polygon and rooms

Use ARKit RoomPlan / Sceneform / Polycam to extract plotPolygon and rooms[]. No API call yet.

4Validate scan quality before paying for audit
const quality = await fetch('/v2/astrology/vastu/ar/scan-quality', {
  method: 'POST', headers,
  body: JSON.stringify({ pointCloudDensity, polygonClosure, compassConfidence,
                         gpsConfidence, roomsTagged, scanDurationSec, scannedAreaM2 })
}).then(r => r.json());
if (!quality.data.acceptForAudit) { showReScanPrompt(quality.data); return; }
5One-shot detailed audit
const audit = await fetch('/v2/astrology/vastu/audit/floor-plan-detailed', {
  method: 'POST', headers,
  body: JSON.stringify({ rooms, plotPolygon, bearingDeg: trueBearing })
}).then(r => r.json());
// audit.data.score, .grade, .defects[], .devataHeatmap[], .mandalaProjection.cells[],
// .remediationOrder[]
6Render in AR scene
audit.data.mandalaProjection.cells.forEach(cell => {
  const color = cell.zone === 'CENTER' ? 'yellow'
    : audit.data.defects.find(d => d.zone === cell.zone) ? 'red' : 'green';
  arScene.addPolygon(cell.polygon, { color, label: cell.zone });
});
7User taps a defect → fetch narrative explanation
onUserTapDefect(defect => {
  fetch('/api/v1/query', {
    method: 'POST', headers,
    body: JSON.stringify({
      question: `Why is my ${defect.room} in the ${defect.zone} a problem?`
    })
  }).then(r => r.json()).then(r => showBottomSheet(r.response));
});

Total per scan: ~$0.10–$0.20 in the typical case. At Pro plan, that's 0.13–0.25% of monthly quota.

Caching, Errors, Idempotency

Caching strategy

Endpoint groupCache lifetimeStorage
Reference data (5 endpoints)App version lifetimeSQLite / CoreData / IndexedDB
Magnetic declination30 days per (lat, lon) round-to-1kmPersistent + memory
Mandala projection / Audit / Entrance padaPer-scan (no reuse)None — input-bound

Error handling with retry + idempotency

async function callVedika(path, body, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const r = await fetch(`https://api.vedika.io${path}`, {
      method: body ? 'POST' : 'GET',
      headers: {
        'Authorization': `Bearer ${VEDIKA_KEY}`,
        'Content-Type': 'application/json',
        'X-Request-Id': makeRequestId()  // idempotency — same UUID = no double-billing
      },
      body: body && JSON.stringify(body)
    });
    if (r.ok) return r.json();
    if (r.status === 429) {
      const retryAfter = parseInt(r.headers.get('Retry-After') || '5', 10);
      await sleep(retryAfter * 1000); continue;
    }
    if (r.status === 402) throw new InsufficientBalanceError(await r.json());
    if (r.status >= 500 && attempt < retries - 1) {
      await sleep(Math.pow(2, attempt) * 1000); continue;  // exponential backoff
    }
    throw new VedikaError(r.status, await r.text());
  }
}

Status code map

StatusMeaningAuto-refund?
400Validation error (bad polygon, missing fields)Yes
401Missing or invalid API key
402Insufficient wallet balance — top up at /dashboard
429Rate limit exceeded — Retry-After header set
500Server error / calculation failureYes

SDK Examples

JavaScript / TypeScript (@vedika-io/sdk)

import { Vedika } from '@vedika-io/sdk';
const vedika = new Vedika({ apiKey: process.env.VEDIKA_KEY });

const audit = await vedika.vastu.audit.floorPlan({
  rooms: [
    { roomType: 'kitchen', zone: 'SE' },
    { roomType: 'toilet',  zone: 'NE' }
  ]
});
console.log(audit.score, audit.grade, audit.defects);

Python (vedika-sdk)

from vedika import Vedika
vedika = Vedika(api_key="vk_live_...")

audit = vedika.vastu.audit.floor_plan(rooms=[
    {"roomType": "kitchen", "zone": "SE"},
    {"roomType": "toilet",  "zone": "NE"},
])
print(audit.score, audit.grade, audit.defects)

Migrating from Other Astrology APIs

What competitors offerVedika equivalentMigration notes
Generic "Vastu remedies" endpoint/vastu/audit/floor-planCleaner contract — structured rooms[] or free-text fallback
Direction lookup/vastu/reference/directions/8Static; cache once at boot
Mandala images (PNG)Polygon coords via /mandala/project/*Render yourself — gives full control over color/opacity/AR overlay
Vastu PDF reportCompose /audit/floor-plan-detailed + your PDF generatorYou control branding
32-pada door classification/vastu/entrance/padaNo competitor offers this — Vedika differentiator.
AR-ready mandala projection/vastu/mandala/project/*No competitor offers this — Vedika differentiator.
Magnetic declination correction/vastu/direction/declinationNo competitor offers this — Vedika differentiator.

Why customers switch

FAQ

Do I need to build a mobile app?

No — the API is purely server-side. You can build the AR/VR client however you want — iOS ARKit, Android Sceneform, WebAR via Polycam or 8thwall, Unity, Unreal, or even a 2D web dashboard. Or skip AR entirely and use the REST endpoints from a server-side proptech listing platform.

What coordinate system do mandala projections use?

Plot-local meters, origin at NW corner, +X = east, +Y = north. Matches Apple ARKit and Google Sceneform conventions — multiply by your AR scene transform matrix and render directly.

How do I tell if I'm in sandbox or production?

Check response.meta.mode. If it equals "sandbox", you're against mock data. If absent, you're in production.

Can I cache the reference data?

Yes — the /reference/* group is static. A typical AR app fetches it once at first launch and stores locally. You only pay $0.012 once for each reference call regardless of subsequent reads.

What if a customer's plot is not rectangular?

Pass any polygon (≥3 vertices). The audit and projection endpoints accept arbitrary polygons. For severely non-rectangular plots, use /plot/shape first to grade — irregular shapes get a warning that classical Vastu rules apply best to subdivided rectangular sub-units.

Are saved scans private?

Saved-scan endpoints (Tier 4 roadmap) store user home layouts only with explicit opt-in retention. Data persists in our regional datastore, never leaves your tenant, is covered by the standard Vedika Data Processing Addendum, and can be deleted on request via the dashboard.

Ready to build?

Try the Sandbox without an API key. Subscribe when you're ready to ship — plans from $12/mo with FREE Sandbox always included.