---
title: "Gemstone Recommendations"
method: POST
path: "/v1/astro/gemstones"
tags: ["Astrology"]
---

# Gemstone Recommendations

`POST /v1/astro/gemstones`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/astro/gemstones`
- Auth: HTTP bearer

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 body

- GemstoneRequest: Gemstone recommendations — same birth fields as :class:`BirthInput` (no ``top_n``).
  - `location` string, nullable: City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.
  - `name` string: Person name associated with the birth record
  - `date` string, required: Birth date in YYYY-MM-DD format
  - `time` string, required: Birth time in HH:MM 24-hour format. Required: this endpoint has no sunrise fallback.
  - `latitude` number, nullable: Latitude. Required if location not provided.
  - `longitude` number, nullable: Longitude. Required if location not provided.
  - `timezone` string, nullable: 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_offset` string, nullable: 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.
  - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Sidereal ayanamsa mode used in calculations

## Response `200`

Successful Response

- ApiResponseGemstoneResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` GemstoneResponse, required
    - `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.
    - `primary` object, required: 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.
    - `secondary` object, nullable: 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.
    - `yogakaraka_gem` object, nullable: 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.
    - `fifth_lord_gem` object, nullable: 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.
    - `ninth_lord_gem` object, nullable: 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.
    - `atmakaraka_gem` object, nullable: 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.
    - `contraindicated` object[], required: 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.
    - `note` string, required

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)