# Vastu Shastra

Vastu Shastra places a house on a square grid of deities, the **Vastu Purusha Mandala**, and reads doors, rooms and water by where they fall on it. Four endpoints cover the parts that can be stated exactly. None of them takes a floor plan image: you send directions, we send back the reading and where it comes from.

## Endpoints

| Endpoint | Credits | What it returns |
|---|---|---|
| `POST /v1/vastu/mandala` | 10 | All 81 cells of the 9x9 grid, the 45 deities, how many padas each holds and which cells |
| `POST /v1/vastu/entrance` | 10 | Which of the 32 outer padas a main door sits in, and the result the text gives for it |
| `POST /v1/vastu/rooms` | 10 | Each room judged ideal, acceptable, avoid or no-rule, and a 0-100 score with its formula |
| `POST /v1/vastu/directions` | 10 | Guardian deity, planet, element, classical use, water and higher ground for the eight directions |

## Where the rules come from

The spine is **Brihat Samhita, chapter 53**, Varahamihira's chapter on house building, in N. Chidambaram Iyer's 1884 translation. It is the one classical text on Vastu that is public domain and has verse numbers you can check. It gives the roster of 45 deities (53.42-50), the result of a door in each of the 32 outer padas (53.72-75), what belongs in four directions (53.118), what a water body does in each of eight (53.119), and the harm of ground raised on each side (53.117).

The second school is **Mayamata**, chapter VII. It uses the same 45 deities, but names four outer padas differently and shares the cells out differently: its cardinal deities hold 6 padas each where Brihat Samhita gives them 3. `school` switches between them.

Everything else people say about Vastu is modern practice: where the toilet goes, the staircase, the septic tank, the bedrooms. Some of it is consistent across writers and some of it contradicts itself. Every judgement in a response carries `basis`: `classical` when a verse stands behind it, `convention` when nothing does.

<Aside type="caution">
**Some rooms are refused.** Dining room, balcony, garage and overhead tank come back 400. The published advice for them disagrees with itself and cites nothing, and an answer that picks one version quietly would look exactly like a fact.
</Aside>

## Entrance

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    curl -X POST https://api.astroway.info/v1/vastu/entrance \
      -H "X-Api-Key: aw_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{ "side": "N", "position": 0.45 }'
    ```
  </TabItem>
  <TabItem label="Node">
    ```js
    const res = await fetch('https://api.astroway.info/v1/vastu/entrance', {
      method: 'POST',
      headers: { 'X-Api-Key': process.env.ASTROWAY_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ pada: 'N4' }),
    });
    const { data } = await res.json();
    console.log(data.devata, data.verdict, data.source);
    ```
  </TabItem>
</Tabs>

`position` is the centre of the door as a fraction of the wall, measured from the corner that leads that wall clockwise: north-east for the east wall, south-east for the south, south-west for the west, north-west for the north. That is the order the verses count in. Or send the pada itself, `N4`.

Of the 32 padas, the text calls **7 auspicious**: E3, E4, W4, W5, N3, N4, N5. Two are mixed (S4, N1) and 23 are harmful. The verdict is our reading of the effect the verse states, and `effect` gives that effect so you can read it yourself.

<Aside type="note">
**Eight doors on a nine-cell wall.** The grid has 9 cells on a side and the text names 8 doors. `method: "eight-per-side"` (the default) splits the wall in eight, as other Vastu APIs do. `method: "mandala-cells"` uses the 9 grid cells and gives each corner to the side that starts there clockwise. The two put some doors in different padas, so the choice is yours, and a door close to a pada edge comes back with a warning.
</Aside>

## Rooms and the score

<Tabs>
  <TabItem label="cURL">
    ```bash frame="terminal"
    curl -X POST https://api.astroway.info/v1/vastu/rooms \
      -H "X-Api-Key: aw_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{ "rooms": [
            { "type": "kitchen", "direction": "SE" },
            { "type": "master-bedroom", "bearing": 225 },
            { "type": "toilet", "direction": "NE" } ] }'
    ```
  </TabItem>
</Tabs>

A direction is where the room sits from the centre of the house: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`, or `C` for the centre (the Brahmasthan). A `bearing` in degrees from true north is read into one of eight 45° sectors.

Room types: `kitchen`, `puja-room`, `store-room`, `underground-water-tank`, `well`, `master-bedroom`, `children-bedroom`, `guest-room`, `study`, `home-office`, `toilet`, `staircase`, `septic-tank`.

**No classical text defines a Vastu score**, and every API that returns one has made it up. Ours is stated in the response so you can check it or compute your own: a rule backed by a verse weighs 2 and a modern rule 1; ideal scores 1, acceptable 0.5, avoid 0. A placement no source covers is `no-rule` and is left out of the score rather than counted as neutral. The example above scores 75: the kitchen is ideal by a verse, the bedroom ideal by modern practice, and the toilet in the north-east is avoided by every writer.

## Mandala

`POST /v1/vastu/mandala` returns the grid with row 0 on the north edge and column 0 on the west, so cell `(0,8)` is the north-east corner. Each cell lists its deity; each deity lists its padas and cells.

In Brihat Samhita, Brahma holds the central 9, four deities around him hold 3 each, the 20 deities of the four corner groups hold 1 each, and the other 20 outer deities hold 2. The verses name one square per deity, not all of them, so the cells of a 2- or 3-pada deity follow from the counts. Mayamata gives counts only for its four corner pairs, so the four cells of each corner block list both names.

## Directions

`POST /v1/vastu/directions` returns the eight directions with their guardian (Amarakosa), planet (Brhajjataka 2.5) and what Brihat Samhita says about each: a water body brings wealth in the north and sons in the north-east and harm everywhere else; the kitchen goes south-east, the shrine north-east. The element of each direction has no verse at all and modern writers disagree on it, so it is marked `convention`.

## What is left out

- **Floor plans as images.** You send directions; nothing is read from a picture.
- **The 16 zones of MahaVastu.** That is one teacher's trademarked system; the sixteen sectors themselves are plain compass division and you can compute them from a bearing.
- **Magnetic declination.** Directions are true north. A compass reading differs by the local declination.