POST/v1/astro/gemstones

Gemstone Recommendations

Recommends gemstones based on the natal chart. Primary gemstone strengthens the Lagna lord (always a functional benefic). Further slots: Yogakaraka, 5th lord, 9th lord, and Atmakaraka. secondary is the first of those that is not the lagna lord's and not contraindicated. Returns contraindicated gemstones: dusthana (6/8/12) lords that own no trikona, debilitated planets, and combust planets — the same rule as POST /v1/crystals/recommend/natal. A slot whose planet is contraindicated carries contraindicated: true and a caution; it is never a silent recommendation. Request JSON follows BirthInput: name, date, time, location or latitude/longitude/timezone, ayanamsa.

Request parameters

locationoptional

string | null

City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.

nameoptional

string

Person name associated with the birth record

daterequired

string

Birth date in YYYY-MM-DD format

timerequired

string

Birth time in HH:MM 24-hour format. Required: this endpoint has no sunrise fallback.

latitudeoptional

number | null

Latitude. Required if location not provided.

longitudeoptional

number | null

Longitude. Required if location not provided.

timezoneoptional

string | null

IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.

utc_offsetoptional

string | null

Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset timezone would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.

ayanamsaoptional

string

Sidereal ayanamsa mode used in calculations

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.birth_time_provided

boolean

True when a birth time was supplied. False when it was not: house, Ascendant and Moon-dependent results then carry the accuracy limits of an unknown birth time.

data.primary

object

Lagna lord's gem: planet, reason, gemstone, substitute_gemstone, metal, colour, note. The lagna lord is always a functional benefic (BPHS Ch.34), so this is never withheld for lordship; it can still be contraindicated when the planet is debilitated or combust. Every slot also carries contraindicated (bool) and caution (string or null): when the slot's planet appears in contraindicated, the slot says contraindicated: true with a caution — do not wear that gem for this role. A 5th/9th lord that also owns a dusthana keeps contraindicated: false with a caution naming the dusthana.

data.secondary

object | null

The first usable second gem: the yogakaraka, 9th lord, 5th lord or Atmakaraka gem, in that order, skipping the lagna lord's and any contraindicated one. role names the slot it came from. Null when none is usable.

data.yogakaraka_gem

object | null

Yogakaraka's gem (planet, gemstone); null when the lagna has no yogakaraka. Every slot also carries contraindicated (bool) and caution (string or null): when the slot's planet appears in contraindicated, the slot says contraindicated: true with a caution — do not wear that gem for this role. A 5th/9th lord that also owns a dusthana keeps contraindicated: false with a caution naming the dusthana.

data.fifth_lord_gem

object | null

5th lord's gem (planet, gemstone). Every slot also carries contraindicated (bool) and caution (string or null): when the slot's planet appears in contraindicated, the slot says contraindicated: true with a caution — do not wear that gem for this role. A 5th/9th lord that also owns a dusthana keeps contraindicated: false with a caution naming the dusthana.

data.ninth_lord_gem

object | null

9th lord's gem (planet, gemstone). Every slot also carries contraindicated (bool) and caution (string or null): when the slot's planet appears in contraindicated, the slot says contraindicated: true with a caution — do not wear that gem for this role. A 5th/9th lord that also owns a dusthana keeps contraindicated: false with a caution naming the dusthana.

data.atmakaraka_gem

object | null

Atmakaraka's gem (planet, gemstone). Every slot also carries contraindicated (bool) and caution (string or null): when the slot's planet appears in contraindicated, the slot says contraindicated: true with a caution — do not wear that gem for this role. A 5th/9th lord that also owns a dusthana keeps contraindicated: false with a caution naming the dusthana.

data.contraindicated

array[object]

Planets whose gem must not be worn in this chart (planet, gemstone, reason): dusthana (6/8/12) lords that own no trikona, debilitated planets, combust planets. Same rule as POST /v1/crystals/recommend/natal.

data.note

string

Errors

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• Personalised Remedies
• Puja Suggestions
• Rudraksha Recommendations

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/astro/gemstones" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1985-11-12","time":"06:45","latitude":19.076,"longitude":72.8777,"timezone":"Asia/Kolkata"}'

Python

import asterwise
from asterwise.api.astrology_api import AstrologyApi
from asterwise.models.gemstone_request import GemstoneRequest

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

request = GemstoneRequest(
    date="1985-11-12",
    time="06:45",
    latitude=19.076,
    longitude=72.8777,
    timezone="Asia/Kolkata",
)

with asterwise.ApiClient(configuration) as client:
    api = AstrologyApi(client)
    result = api.gemstones(gemstone_request=request)
    print(result)

TypeScript

import { createClient, createConfig, gemstones } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await gemstones({
  client,
  body: {
      "date": "1985-11-12",
      "time": "06:45",
      "latitude": 19.076,
      "longitude": 72.8777,
      "timezone": "Asia/Kolkata"
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "primary": {
      "planet": "Venus",
      "reason": "Lagna lord — strengthens the ascendant and overall vitality",
      "gemstone": "Diamond",
      "substitute_gemstone": "White Zircon",
      "metal": "Silver",
      "colour": "White",
      "note": "Use with caution in charts where Venus rules difficult houses.",
      "contraindicated": false,
      "caution": null
    },
    "yogakaraka_gem": {
      "planet": "Saturn",
      "gemstone": "Blue Sapphire",
      "contraindicated": true,
      "caution": "Contraindicated in this chart — Saturn: combust — planet has no light. Do not wear this gem for this role."
    },
    "fifth_lord_gem": {
      "planet": "Saturn",
      "gemstone": "Blue Sapphire",
      "contraindicated": true,
      "caution": "Contraindicated in this chart — Saturn: combust — planet has no light. Do not wear this gem for this role."
    },
    "ninth_lord_gem": {
      "planet": "Mercury",
      "gemstone": "Emerald",
      "contraindicated": false,
      "caution": "Mercury also owns the 12th house (a dusthana). Trikona lordship keeps it a functional benefic, but its gem can also stre…"
    },
    "atmakaraka_gem": {
      "planet": "Sun",
      "gemstone": "Ruby",
      "contraindicated": true,
      "caution": "Contraindicated in this chart — Sun: debilitated — amplifies worst qualities. Do not wear this gem for this role."
    },
    "secondary": {
      "planet": "Mercury",
      "gemstone": "Emerald",
      "contraindicated": false,
      "caution": "Mercury also owns the 12th house (a dusthana). Trikona lordship keeps it a functional benefic, but its gem can also stre…",
      "role": "ninth_lord"
    },
    "contraindicated": [
      {
        "planet": "Sun",
        "gemstone": "Ruby",
        "reason": "debilitated — amplifies worst qualities"
      },
      {
        "planet": "Moon",
        "gemstone": "Pearl",
        "reason": "combust — planet has no light"
      },
      "... and 2 more items"
    ],
    "note": "Gemstone recommendations are based on classical Vedic principles. Always consult a qualified astrologer before wearing g…"
  }
}