Ratna (gemstone remedies)

Ratna (रत्न) is a gemstone worn as a remedy for a graha. Nine gems, the navaratna, one per graha. “Which stone should I wear” sounds like a simple question, but the answer depends on the school, and the two common schools forbid different things. So /v1/vedic/gemstones takes the school as a parameter and always reports which one produced the answer.

The two schools

School	What it prescribes	What it withholds
lagna-lord (default)	The gems of the 1st, 9th and 5th lords: the life, lucky and benefic stone	Almost nothing: only a graha owning nothing but dusthanas
functional-benefic	The same three gems, but the yogakaraka leads where one exists	The gems of every functional malefic for that lagna

The recommended gems coincide in both schools, and not by accident: a functional benefic is defined as a graha owning a trikona, and the trikona lords are exactly the lords of the 1st, 5th and 9th. We did not assume that, we ran both schools across all twelve lagnas and pinned the result in a test.

The difference sits where it matters to a buyer: the avoid list. For a Leo lagna, functional-benefic withdraws emerald, diamond and blue sapphire; lagna-lord withdraws none of them. If your astrologer works in one school and you hand your customer the other school’s answer, this is exactly where they will disagree.

Endpoints

Endpoint	Credits	What it returns
POST /v1/vedic/gemstones	20	Chart-based recommendation: three gems with their role, the avoid list, cautions, planet condition
GET /v1/vedic/gemstones/navaratna	5	The nine-gem reference table, no chart needed

Caution

Coordinates are required. The whole answer is derived from the lagna, so latitude and longitude do not default to zero here as they do on other chart endpoints: omit them and you get a 400, not a confident set of gems for someone else’s ascendant.

Example

cURL

curl -X POST https://api.astroway.info/v1/vedic/gemstones \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52,
    "school": "functional-benefic"
  }'

Node.js

const r = await fetch('https://api.astroway.info/v1/vedic/gemstones', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    date: '1990-05-15', time: '14:30:00', timezoneOffset: 3,
    latitude: 50.45, longitude: 30.52, school: 'functional-benefic',
  }),
});
const { data } = await r.json();
console.log(`Lagna ${data.lagna.signName}, school ${data.school}`);
for (const g of data.recommended) console.log(`  ${g.role}: ${g.gem}`);
for (const g of data.avoid) console.log(`  avoid ${g.gem} (${g.basis})`);

Python

import os, requests

r = requests.post(
    'https://api.astroway.info/v1/vedic/gemstones',
    headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY']},
    json={
        'date': '1990-05-15', 'time': '14:30:00', 'timezoneOffset': 3,
        'latitude': 50.45, 'longitude': 30.52, 'school': 'functional-benefic',
    },
)
d = r.json()['data']
print(f"Lagna {d['lagna']['signName']} ({d['school']})")
for g in d['recommended']:
    w = g['wearing']
    print(f"  {g['gem']:16s} {w['day']:10s} {w['finger']:14s} {w['minWeight']['carats']} ct")

Sample response

{
  "type": "gemstone-recommendation",
  "school": "functional-benefic",
  "ayanamsa": 23.7225,
  "lagna": { "sign": 4, "signName": "Leo", "lord": 0, "lordName": "Sun" },
  "recommended": [
    {
      "role": "yogakaraka (primary)",
      "graha": 4, "grahaName": "Mars",
      "gem": "Red coral", "gemSanskrit": "Moonga",
      "mineral": "Corallium rubrum",
      "housesOwned": [4, 9],
      "basis": "owns the 4th (kendra) and the 9th (trikona)",
      "substitutes": ["Carnelian", "Red jasper"],
      "wearing": {
        "day": "Tuesday",
        "finger": "Ring finger",
        "metals": ["Gold", "Copper"],
        "minWeight": { "ratti": [6, 9], "grams": [0.729, 1.094], "carats": [3.65, 5.47] },
        "mantra": "Om Kraam Kreem Kraum Sah Bhaumaya Namah",
        "japaCount": 10000
      }
    }
  ],
  "avoid": [
    { "gem": "Blue sapphire", "basis": "owns the 6th and no trikona" },
    { "gem": "Emerald", "basis": "owns the 11th and no trikona" }
  ],
  "condition": {
    "Sun": { "signName": "Taurus", "house": 10, "dignity": "neutral", "isCombust": false }
  },
  "disclaimer": "Traditional Jyotish remedy, informational only..."
}

What comes back

• basis on every gem is a trace, not a label: which houses the graha owns and why that gives it this role. A recommendation you can check instead of taking on trust.
• wearing carries the day, finger, metals, weight in ratti with gram and carat conversions, the beeja mantra and the japa count. Weight is a range and the finger a list of variants, because the manuals disagree.
• substitutes (upa-ratna): in practice the alternative to a 5-carat natural blue sapphire is not “no remedy” but a cheaper stand-in. Anyone pricing a recommendation needs both.
• condition reports dignity, combustion and retrogression for each graha. It is context, not a rule: both schools prescribe by house ownership, and claiming otherwise would be inventing a third school.
• nodesNote: Rahu and Ketu own no sign, so neither school can reach hessonite or cat’s eye from the lagna. We say so rather than quietly returning seven gems out of nine.

Accuracy and sources

• Gem to graha: the Garuda Purana (Acharakanda, ratna-pariksha) and Varahamihira, Brihat Samhita ch. 80. Both texts give the same nine-gem set.
• The three-stone rule (life, lucky, benefic) is standard modern practice.
• Functional classification: Bepin Behari, Fundamentals of Vedic Astrology. The yogakaraka rule itself is BPHS: a graha owning both a kendra and a trikona.
• How it was checked. This is not a numerical technique, so there is nothing to drift against an ephemeris. One check is possible: the rules have to reproduce the published prescriptions without those being hardcoded anywhere. The classical six yogakarakas (Saturn for Taurus and Libra, Mars for Cancer and Leo, Venus for Capricorn and Aquarius) fall out of the ownership rule on their own, as do the well-known avoid lists for Aries, Taurus, Cancer and Leo. Each of those statements is a test.
• The lagna is sidereal, derived through the ayanamsa. A tropical ascendant is usually a whole sign off, which would change every gem in the answer.
• The wearing protocol (day, finger, metal, weight, mantra) is modern practice rather than scripture. Hence variants and a range, not one number presented as canon.

Danger

A remedy, not medicine and not a purchase appraisal. Gem identity, treatment and weight must be confirmed by a qualified gemmologist or jeweller before purchase. No gemstone substitutes for medical care: consult a licensed physician for any health concern. This boundary ships in every response from the endpoint.

Related

• Shadbala, planetary strength, for a quantitative rather than a remedial view
• Doshas, Mangal, Kaal Sarp and the other afflictions a gem is traditionally chosen against
• Vargas, divisional charts
• Credits, the full pricing table
• Authentication, how to get an aw_live_* key