Vastu Shastra API, what to build and how to call it

Ship an entrance checker, a mandala overlay on a floor plan, a room by room compliance report, or a griha pravesh date finder in under 30 minutes. No consultant training required.

Vastu Shastra is directional design for homes and plots: where the door goes, what each quarter of the ground is for, and what proportion the building takes. It is a full domain in the RoxyAPI catalog, 10 endpoints computed from typed geometry rather than looked up in a table. What makes it different from a free rules engine is the citation: every verdict carries a source object naming the text, chapter, verse, translator and edition year, or the literal value convention with the practice it rests on. Directions are the same identifiers the feng shui endpoints use, so a Vastu quarter and a flying star palace compare without a lookup table.

What you can build

• Entrance checkers (which of the 32 perimeter padas a main door falls on, and which padas on the same side to move it toward)
• Mandala overlays for floor plans (every square with its devata, the brahmasthan as a polygon, the marma points, the vamsa diagonals)
• Room by room compliance reports over a closed set of twelve room types, with a remedy per room and a composite score
• Plot verdicts for listing platforms (shape, proportion, ground level, corner extensions and cuts, the road, standing water)
• Ayadi proportion calculators showing the multiplier, divisor, product and remainder for every varga
• Griha pravesh date finders over a season, each day carrying the rules that qualified it
• Reference libraries for the eight directions and the 45 devatas, for explainer pages and structured content
• Practitioner report tools where half the page is classical and the other half is labelled as practice

Prerequisites

1. A RoxyAPI key from /account.
2. A plot. Send plot.width and plot.depth for a compass aligned rectangle, or plot.polygon as 3 to 16 vertices for anything else. The x axis runs east and the y axis runs north.
3. A facing, on every route that reads one. Either facing (one of the eight sectors, such as East) or facingDegrees (a bearing 0 to 360 measured looking out from the building). Never both.
4. For the date search only: a latitude, longitude, timezone and a window of at most 93 days. No birth chart is needed anywhere in this domain, so GET /location/search is the only extra call a form ever needs.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

go get github.com/RoxyAPI/sdk-go

Call the endpoint

The #1 Vastu call is the entrance. One POST turns a plot plus a door into the pada it lands on, the devata of that square, the classical effect and the better padas on the same side. Verified operationId: calculateEntrancePada.

curl -X POST https://roxyapi.com/api/v2/vastu/entrance \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plot": { "width": 30, "depth": 40 },
    "facing": "East",
    "doorPosition": 0.3
  }'

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: entrance } = await roxy.vastu.calculateEntrancePada({
  body: { plot: { width: 30, depth: 40 }, facing: 'East', doorPosition: 0.3 },
});

console.log(entrance.pada);             // 3
console.log(entrance.side);             // "East"
console.log(entrance.startCorner);      // "Northeast"
console.log(entrance.square);           // 3
console.log(entrance.devata.name);      // "Jayanta"
console.log(entrance.effect);           // "Great wealth."
console.log(entrance.auspiciousness);   // "auspicious"
console.log(entrance.recommendedPadas); // [3, 4]
console.log(entrance.source.verse);     // "72"

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

entrance = roxy.vastu.calculate_entrance_pada(
    plot={'width': 30, 'depth': 40}, facing='East', door_position=0.3,
)
print(entrance['pada'], entrance['devata']['name'], entrance['auspiciousness'])
print(entrance['source']['text'], entrance['source']['chapter'], entrance['source']['verse'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$entrance = $roxy->vastu->calculateEntrancePada(
    plot: ['width' => 30, 'depth' => 40],
    facing: 'East',
    doorPosition: 0.3,
);
echo $entrance['pada'], ' ', $entrance['devata']['name'], ' ', $entrance['effect'];

using RoxyApi;
using RoxyApi.Vastu.Entrance;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var entrance = await roxy.Vastu.Entrance.PostAsync(new()
{
    Plot = new() { Width = 30, Depth = 40 },
    Facing = EntrancePostRequestBody_facing.East,
    DoorPosition = 0.3,
});

Console.WriteLine(entrance!.Pada);            // 3
Console.WriteLine(entrance.Devata!.Name);     // "Jayanta"
Console.WriteLine(entrance.Auspiciousness);   // "auspicious"

import (
    "context"
    roxyapi "github.com/RoxyAPI/sdk-go"
)

roxy, _ := roxyapi.NewRoxy("YOUR_API_KEY")

body := roxyapi.CalculateEntrancePadaJSONRequestBody{
    Facing:       roxyapi.Ptr(roxyapi.CalculateEntrancePadaJSONBodyFacingEast),
    DoorPosition: roxyapi.Ptr(float32(0.3)),
}
body.Plot.Width = roxyapi.Ptr(float32(30))
body.Plot.Depth = roxyapi.Ptr(float32(40))

entrance, _ := roxy.Vastu.CalculateEntrancePada(context.Background(), nil, body)

claude mcp add-json --scope user roxy-vastu '{"type":"http","url":"https://roxyapi.com/mcp/vastu","headers":{"X-API-Key":"YOUR_KEY"}}'

Read the response

That call returns this, in full:

{
  "pada": 3,
  "side": "East",
  "startCorner": "Northeast",
  "ordinalOnSide": 3,
  "square": 3,
  "cell": { "rowFromNorth": 3, "columnFromWest": 9 },
  "devata": { "id": "jayanta", "name": "Jayanta", "padaCount": 2 },
  "effect": "Great wealth.",
  "auspiciousness": "auspicious",
  "reading": "The main entrance falls on pada 3 of the East side, counted from the Northeast corner. That pada is the square of Jayanta. Great wealth.",
  "recommendedPadas": [3, 4],
  "source": {
    "text": "Brihat Samhita",
    "chapter": 53,
    "verse": "72",
    "translation": "N. Chidambaram Iyer",
    "year": 1884,
    "publicDomain": true
  },
  "conventions": { "grid": "81-pada" }
}

Branch on auspiciousness, which never translates, and render reading and effect, which do.

The source object is the point

Every verdict in this domain carries one, and it has exactly two shapes. A cited rule:

{ "text": "Brihat Samhita", "chapter": 53, "verse": "119", "translation": "N. Chidambaram Iyer", "year": 1884, "publicDomain": true }

And a rule that rests on practice rather than a verse:

{ "text": "convention", "basis": "chapter 53 states no rule for the side a road runs on; 53.76 bars an obstruction facing the gate unless it lies beyond twice the height of the house" }

text is the discriminator. When it is the literal string convention there is no chapter, verse, translation or year, and basis is present instead. That is the only branch a renderer needs:

const cite = (s: Source) =>
  s.text === 'convention' ? `Practice: ${s.basis}` : `${s.text} ${s.chapter}.${s.verse}`;

publicDomain is true on every Brihat Samhita citation, whose verses are quoted from the 1884 edition, so the citation is safe to print in a client report. It is false on the Manasara citations behind the Ayadi formulas: that 1933 edition is still in copyright, so only the multipliers, divisors and names are taken from it, never a sentence.

Ship the rest

Room by room compliance

POST /vastu/rooms (calculateRoomCompliance) takes a plot, a facing and a list of rooms, each as a type plus either a direction or a polygon. The twelve types are puja, kitchen, master-bedroom, bedroom, living, dining, study, toilet, store, staircase, water-storage and entrance.

curl -X POST https://roxyapi.com/api/v2/vastu/rooms \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"plot":{"width":30,"depth":40},"facing":"East",
       "rooms":[{"type":"kitchen","direction":"Southeast"},
                {"type":"toilet","direction":"Northeast"}]}'
# => rooms[0] verdict "ideal", rooms[1] verdict "avoid",
#    score 66.7, scoring { sourcedWeight: 2, conventionWeight: 1, idealPoints: 1, ... }

Each room comes back with zone, verdict, idealDirections, avoidDirections, a composed reading, a remedy and its own source. The kitchen carries a verse (53.118); the toilet carries convention, because the chapter places no toilet. scoring publishes the weights the composite score was built from, so a UI can show the working instead of asserting a number.

Plot analysis

POST /vastu/plot (calculatePlotAnalysis) reads the ground itself: shape, ratio, slope, water, extensions, cuts and road, each with its own verdict and source.

curl -X POST https://roxyapi.com/api/v2/vastu/plot \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"plot":{"width":30,"depth":40},"facing":"East",
       "slopeLowDirection":"Northeast","road":"East","water":"Northeast"}'
# => shape.verdict "regular", dimensions { length: 40, breadth: 30, area: 1200, ratio: 1.333 },
#    water.effect "Sons.", slope.schools[0] { school: "brihat-samhita", verdict: "not-stated" },
#    slope.schools[1] { school: "modern", verdict: "auspicious" }

slopeLowDirection is where the ground is LOW, not where it stands high, and slope.highDirection comes back beside it so nothing is ambiguous. slope.schools always carries BOTH readings whichever school you asked for, because the classical verses and the modern teaching genuinely disagree, and slope.chosen names the one you led with.

The mandala over a real plot

POST /vastu/mandala (generateMandala) projects the Vastu Purusha Mandala over the plot and returns geometry you can draw:

curl -X POST https://roxyapi.com/api/v2/vastu/mandala \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"plot":{"width":30,"depth":40}}'
# => grid "81-pada", cells 81 entries, brahmasthan.squares [31,32,33,40,41,42,49,50,51],
#    brahmasthan.area 133.33, vamsa 6 lines, atimarma [23,31,33,39,41,43,49,51,59],
#    marma.areaEach 1.85

Every entry in cells carries square, rowFromNorth, columnFromWest, devata, devataName, class, a center point in your own plot coordinates, and withinPlot, which is false for a square that falls outside an irregular boundary. brahmasthan.polygon is the central block as a polygon, ready to drop onto a plan. vamsa is the six diagonals named by their devata endpoints, each with axis and isMainDiagonal. atimarma is the nine squares where those lines cross.

Ayadi shadvarga

POST /vastu/ayadi (calculateAyadi) runs the six proportional formulas and shows the arithmetic:

curl -X POST https://roxyapi.com/api/v2/vastu/ayadi \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"length":12,"breadth":9,"unit":"hasta"}'
# => vargas aya, vyaya, yoni, rksha, tithi, vara; vayas 12,
#    verdict { yoniAuspicious: true, ayaVyaya: "zero-remainder" }

Each varga carries operand, operandValue, multiplier, divisor, product, remainder and groupSize, so the whole calculation can be checked by hand rather than trusted. verdict.ayaVyaya is one of aya-greater, equal, aya-lesser or zero-remainder, canonical English, and verdict.reading is the sentence. Where no public domain source prints the member names for a group, the response returns the remainder and the group size and invents nothing.

Griha pravesh dates

POST /vastu/timing/griha-pravesh (findGrihaPraveshDates) scans a window of at most 93 days against a verified panchang.

curl -X POST https://roxyapi.com/api/v2/vastu/timing/griha-pravesh \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"startDate":"2026-04-01","endDate":"2026-05-31",
       "latitude":12.9716,"longitude":77.5946,"timezone":"Asia/Kolkata"}'
# => total 7, window.daysEvaluated 61,
#    days[0] { date: "2026-04-03", nakshatra: { number: 14, id: "chitra" },
#              tithi: { number: 16, name: "Pratipada", paksha: "Krishna" },
#              vara: { name: "Friday" }, quality: "preferred",
#              admittedBy: ["nakshatra-admissible", "tithi-window", ...] }

admittedBy names the limbs that qualified each day, rules publishes every rule with its requirement, confidence and source, and rejectionsByRule counts which rule knocked out how many days, which is what a UI shows when a window returns nothing. leftToTheAstrologer is the load bearing one: the lagna rules, the eighth from the owner birth moon sign and the combustion checks are judgements about a moment and about a person, so they are published rather than quietly dropped.

The catalogs

• GET /vastu/directions (listDikpalaDirections) returns the eight directions with dikpala, kind, the mandala squares and the devatas on them, and the water effect for that quarter. Soma on the north, Isana on the north-east, Indra on the east, Agni on the south-east, Yama on the south, Nirriti on the south-west, Varuna on the west, Vayu on the north-west.
• GET /vastu/directions/{id} (getDikpalaDirection) is one of them in full, adding element and places, the activity the chapter puts in that quarter. Ids are the sector names and case is folded, so northeast, north-east and Northeast all resolve.
• GET /vastu/devatas (listDevatas) is the 45 devatas, paginated with total, limit and offset.
• GET /vastu/devatas/{id} (getDevata) is one row: class, group, side, quadrant, squares, cells, padaCount, entrancePada, a composed role, the verses it rests on and, where two texts disagree, a note recording the other reading rather than resolving it.

curl https://roxyapi.com/api/v2/vastu/devatas/brahma -H "X-API-Key: $ROXY_API_KEY"
# => squares [31,32,33,40,41,42,49,50,51], padaCount 9, verses ["53.46"],
#    role "The devata Brahmā holds the nine central squares of the mandala."

See the full domain at the API Reference.

The conventions are typed, defaulted and echoed

Vastu is not one school. Where two texts disagree, this API takes the disagreement as an input instead of picking silently. Every switch is optional, has a named default, and comes back in conventions on the response, so a reading stored today can be reproduced years from now without knowing what the defaults were on the day it was made.

Two of these are worth a line in your own UI. unit and hastaInches are inputs, never assumptions, because every Ayadi remainder is unit sensitive: the same building measured in cubits and in feet gives different remainders, and a silent default is what makes a stored reading irreproducible. Three independent sources put the cubit at 18 inches, which is why that is the default rather than a guess.

The plot geometry has its own unit under plot.unit, which is feet by default and is a different field from the Ayadi one. The mandala projection is scale free, so plot.unit only affects areas and the marma size.

Reply in the user language

Every route accepts ?lang=. This domain ships German, Spanish, French, Hindi, Portuguese, Russian and Turkish alongside the English source.

curl -X POST "https://roxyapi.com/api/v2/vastu/entrance?lang=hi" \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"plot":{"width":30,"depth":40},"facing":"East","doorPosition":0.3}'

Machine readable identifiers never translate. auspiciousness stays "auspicious", side stays "East", verdict stays "ideal", grid stays "81-pada", and source.text stays "Brihat Samhita" or the literal "convention". Composed prose does translate in place: reading, effect, remedy, role and requirement. Branch on the identifier, render the prose.

Gotchas

• doorPosition needs a cardinal facing. An intercardinal facing names no single side, so facing: "Northeast" with a doorPosition returns 400. Send door coordinates instead. The fraction runs from the corner the chapter starts that side at, which startCorner names on the way back.
• Send door or doorPosition, never both. Same for facing and facingDegrees, for plot.width plus plot.depth against plot.polygon, and for a room direction against a room polygon. Each pair returns 400 with the message naming the pair.
• slopeLowDirection is where the ground is LOW. The verses are stated in terms of the side that stands higher, so sending the high side inverts every slope verdict. Omit it entirely if the ground is level.
• Both slope schools always come back. Reading only slope.schools[0] and ignoring chosen will silently show one school in a UI that offered a switch.
• A quarter cannot be both extended and cut. Passing the same direction in extensions and cuts returns 400 rather than resolving it.
• The mandala is aligned to the COMPASS, not to the building. facing says which side the front is on and never rotates the grid. The x axis runs east and the y axis runs north, whatever the house does.
• The 64 pada grid names no devata. On grid: "64-pada" the entrance route returns the pada and its effect but no devata, and the mandala carries no marma, vamsa or atimarma geometry, because the chapter gives that grid structure only.
• source.text of convention is a real answer, not a gap. Many verdicts in this domain rest on later practice because the chapter states no rule, and saying so is the product. Render basis rather than hiding the row.
• The date search evaluates DAY level rules only. Anything about a moment or about a person is in leftToTheAstrologer. A UI that presents the results as a final answer is overstating them.
• The window is capped at 93 days. A wider range returns 400 naming the cap and the span you asked for.
• Every call bills at a flat 1 request. REST and Remote MCP are identical, with no per-domain fees.

Frequently asked questions

Ready-made starter

There is no Vastu only template yet. The flagship astrology-ai-chatbot template connects every domain over Remote MCP by default, so cloning it gives you a working entrance and mandala chatbot with no wiring; browse the catalog at /starters. For a custom build, the Next.js integration guide is the fastest path.

What to build next

• The feng shui guide covers the other directional system in the catalog. The two share the same eight sector identifiers and the same facing convention, so a single compass input drives both.
• The Vedic astrology guide covers the panchang the griha pravesh search reads, if you want the nakshatra, tithi and yoga for a date on their own.
• The caching guide covers the split this domain has: geometry answers never change, a date search over a fixed window never changes either, and neither needs a refresh schedule.
• The AI chatbot tutorial shows tool registration so users can ask "is my kitchen in the right corner" in natural language.