# 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](/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`](/api-reference#tag/location-and-timezone/GET/location/search) is the only extra call a form ever needs. ## Install ### npm ```bash npm install @roxyapi/sdk ``` ### Python ```bash pip install roxy-sdk ``` ### PHP ```bash composer require roxyapi/sdk ``` ### .NET CLI ```bash dotnet add package RoxyApi.Sdk ``` ### Go ```bash 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 ```bash 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 }' ``` ### TypeScript SDK ```typescript 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" ``` ### Python SDK ```python 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 SDK ```php vastu->calculateEntrancePada( plot: ['width' => 30, 'depth' => 40], facing: 'East', doorPosition: 0.3, ); echo $entrance['pada'], ' ', $entrance['devata']['name'], ' ', $entrance['effect']; ``` ### C# SDK ```csharp 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" ``` ### Go SDK ```go 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) ``` ### MCP ```bash claude mcp add-json --scope user roxy-vastu '{"type":"http","url":"https://roxyapi.com/mcp/vastu","headers":{"X-API-Key":"YOUR_KEY"}}' ``` Then in any MCP client: "my plot is 30 by 40 feet facing east and the main door is a third of the way along the front, is that a good entrance?" The agent calls the entrance tool and reads the pada, the effect and the padas it recommends instead. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp). ## Read the response That call returns this, in full: ```json { "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" } } ``` | Field | What it is | |---|---| | `pada` | Which of the 32 perimeter positions the door falls on, 1 to 32 running round the plot | | `side` | `North`, `East`, `South` or `West`, the side that pada belongs to | | `startCorner` | The corner the chapter counts that side from, so a UI can draw the numbering the right way round | | `ordinalOnSide` | Position 1 to 8 within the side, which is usually what a floor plan label wants | | `square` and `cell` | Where the pada sits on the mandala grid, as a square number and a row and column | | `devata` | The devata holding that square, with `id`, `name` and `padaCount` | | `effect` | The stated effect of a door on that pada, from the verse | | `auspiciousness` | `auspicious`, `mixed` or `inauspicious`, canonical English in every language | | `reading` | The whole verdict as one sentence, ready to print in a report | | `recommendedPadas` | The favourable padas on the SAME side, so a suggestion never asks anyone to move a wall | | `source` | Where the verdict comes from, see below | | `conventions` | Every switch this result was computed with, echoed so it can be reproduced | 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: ```json { "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: ```json { "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: ```typescript 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`](/api-reference#tag/vastu/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`. ```bash 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`](/api-reference#tag/vastu/POST/vastu/plot) (`calculatePlotAnalysis`) reads the ground itself: `shape`, `ratio`, `slope`, `water`, `extensions`, `cuts` and `road`, each with its own verdict and `source`. ```bash 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`](/api-reference#tag/vastu/POST/vastu/mandala) (`generateMandala`) projects the Vastu Purusha Mandala over the plot and returns geometry you can draw: ```bash 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. **Tip: Draw the brahmasthan first** It is the one part of a plan a reviewer looks for, and `brahmasthan.polygon` plus `brahmasthan.area` is a complete answer with no geometry of your own. ### Ayadi shadvarga [`POST /vastu/ayadi`](/api-reference#tag/vastu/POST/vastu/ayadi) (`calculateAyadi`) runs the six proportional formulas and shows the arithmetic: ```bash 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`](/api-reference#tag/vastu/POST/vastu/timing/griha-pravesh) (`findGrihaPraveshDates`) scans a window of at most 93 days against a verified panchang. ```bash 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`](/api-reference#tag/vastu/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}`](/api-reference#tag/vastu/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`](/api-reference#tag/vastu/GET/vastu/devatas) (`listDevatas`) is the 45 devatas, paginated with `total`, `limit` and `offset`. - [`GET /vastu/devatas/{id}`](/api-reference#tag/vastu/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. ```bash 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](/api-reference#tag/vastu). ## 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. | Convention | Values | Default | Routes | What it changes | |---|---|---|---|---| | `grid` | `81-pada`, `64-pada` | `81-pada` | entrance, mandala | Which division of the ground is read. The 81 pada Paramasayika names a devata on every square. The 64 pada Manduka is structure only, so it carries no devata, no marma and no vamsa geometry | | `ayadiText` | `manasara`, `perimeter-texts`, `utpala` | `manasara` | ayadi | Which family supplies the multipliers. They read different measures and give different remainders for the same building | | `vyayaFormula` | `p9-10`, `p3-14` | `p9-10` | ayadi | Which vyaya formula the perimeter family uses. The printed table gives both joined by the word or and states no rule for choosing. Ignored under `manasara`, which has one | | `slopeSchool` | `brihat-samhita`, `modern` | `brihat-samhita` | plot | Which ground level reading leads. Both come back either way | | `unit` | `hasta`, `feet`, `metres` | `hasta` | ayadi | Which unit the Ayadi dimensions arrive in. Feet and metres are converted and the rounded cubit figures are returned | | `hastaInches` | any positive number | `18` | ayadi | How long one cubit is taken to be | | `muhurtaText` | `muhurta-chintamani`, `kalaprakasika` | `muhurta-chintamani` | griha pravesh | Which Muhurta text supplies the admissible nakshatras, eight against twelve, with seven overlapping | 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. ```bash 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 ### Which direction should the main entrance face? The classical answer is not a direction but a pada. The perimeter divides into 32 positions, eight to a side, and each carries its own stated effect, so a north facing door on a poor pada is worse than a south facing one on a good pada. `POST /vastu/entrance` returns the pada, the devata of that square, the effect, and `recommendedPadas`, the favourable positions on the same side to move toward. ### What is the brahmasthan and how do I draw it? It is the central block of the mandala, nine squares of the eighty one or four of the sixty four, held by Brahma, and it is the part of a plan kept open. `POST /vastu/mandala` returns `brahmasthan.squares`, `brahmasthan.polygon` in your own plot coordinates and `brahmasthan.area`, so it can be drawn straight onto a floor plan and checked against what stands there. ### Why does the ground level verdict differ from what a consultant said? Because the classical verses and the modern teaching disagree, and the API returns both instead of choosing. The verses call a higher north-east a loss and expressly allow a slight rise on the east or north where level ground is unavoidable; the modern rule wants the north-east lowest and permits neither. Send `slopeSchool` to say which leads, and the other reading comes back beside it with its verse or with a plain statement that it rests on practice. ### What is Ayadi shadvarga and what does the calculator return? Six proportional formulas applied to the dimensions of a building, each multiplying a measure and taking the remainder of a division. `POST /vastu/ayadi` returns the multiplier, divisor, product and remainder for all six, the member each remainder names where a source names one, and the two verdict rules the texts state. Where the aya and vyaya name lists are not printed in any public domain source, it returns the remainder and the group size and no invented name. ### Does any of this need a birth chart? No. Every route takes geometry, a facing and, for the date search, a place and a window. There is no owner chart route and no numerological facing route, because no primary text ties a birth nakshatra or a radical number to a house facing. The date search applies the owner independent rules and publishes the owner dependent ones in `leftToTheAstrologer`. ### Does it work outside India? Yes. The mandala is geometry aligned to the compass, so it projects over a plot in Lisbon exactly as over one in Chennai, and the direction identifiers are the ones the feng shui endpoints already use. The date search takes any latitude, longitude and offset, reads every limb at local sunrise, and falls back to local midnight rather than refusing inside a polar night. ## Ready-made starter There is no Vastu only template yet. The flagship [astrology-ai-chatbot](https://github.com/RoxyAPI/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](/starters). For a custom build, the [Next.js integration guide](/docs/integrations/nextjs) is the fastest path. ## What to build next - The [feng shui guide](/docs/guides/feng-shui) 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](/docs/guides/vedic-astrology) 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](/docs/guides/caching) 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](/docs/tutorials/ai-chatbot) shows tool registration so users can ask "is my kitchen in the right corner" in natural language.