POST/v1/crystals/recommend/natal

Natal Chart Crystal Recommendations

Recommend crystals from the natal chart's functional benefics, using the same rule as POST /v1/astro/gemstones (BPHS Ch.34 lordship, whole-sign from the lagna). Recommended: the lagna lord (always auspicious) = Life Stone (+5), the Yogakaraka = supreme benefic (+5), the 9th lord = Fortune Stone (+4), the 5th lord = Lucky Stone (+3). A 5th/9th lord that also owns a Dusthana (6, 8, 12) is still recommended, with that Dusthana named in warnings[]. Contraindicated (natal_context.contraindicated_lords, never returned): Dusthana lords that own no Trikona, and debilitated or combust planets. Kendra-only and 2nd/3rd/11th lords are neither recommended nor contraindicated. Only crystals with Vedic assignments (Navaratna or Uparatna) are returned. Dangerous gem combinations are flagged in warnings[].

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.natal_context

object

data.natal_context.lagna_sign

string

Ascendant sign (English).

data.natal_context.lagna_lord

string

Lord of the 1st house.

data.natal_context.fifth_sign

string

5th house sign (English).

data.natal_context.fifth_lord

string

Lord of the 5th house (Panchamesh — Lucky Stone).

data.natal_context.ninth_sign

string

9th house sign (English).

data.natal_context.ninth_lord

string

Lord of the 9th house (Bhagyesh — Fortune Stone).

data.natal_context.yogakaraka

string | null

Yogakaraka planet — lords both a non-1st Kendra and a non-1st Trikona. Null if none for this Lagna.

data.natal_context.contraindicated_lords

array[string]

Planets whose gems are contraindicated in this chart: Dusthana (6/8/12) lords that own no Trikona, plus debilitated or combust planets. Same rule as POST /v1/astro/gemstones.

data.natal_context.ayanamsa

string

Ayanamsa the chart was cast with: the request's ayanamsa (until 2026-10 this always read "lahiri").

data.total

integer

data.crystals

array[object]

data.crystals[].slug

string

data.crystals[].name

string

data.crystals[].colors

array[string]

data.crystals[].hardness_mohs

number

data.crystals[].chakras

array[string]

data.crystals[].element

string

data.crystals[].zodiac_signs

array[string]

data.crystals[].vedic_planet

string | null

data.crystals[].vedic_correspondence

string

data.crystals[].western_planet

string | null

data.crystals[].keywords

array[string]

data.crystals[].healing_physical

string

data.crystals[].healing_emotional

string

data.crystals[].healing_spiritual

string

data.crystals[].description

string

data.crystals[].origins

array[string]

data.crystals[].affirmation

string

data.crystals[].caution

string | null

data.crystals[].match_score

integer

Gemstone match score based on house lordship.

data.crystals[].match_reasons

array[string]

Classical factors — which house lordship triggered this recommendation.

data.crystals[].warnings

array[string]

Classical cautions for this specific chart context.

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

• Single crystal lookup
• Crystal recommendations
• Crystals by Vedic planet
• Complete crystal database

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/crystals/recommend/natal" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Arjun Mehta","date":"1985-11-12","time":"06:45","location":"Mumbai"}'

Python

import asterwise
from asterwise.api.crystals_api import CrystalsApi
from asterwise.models.natal_crystal_request import NatalCrystalRequest

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

request = NatalCrystalRequest(
    name="Arjun Mehta",
    date="1985-11-12",
    time="06:45",
    location="Mumbai",
)

with asterwise.ApiClient(configuration) as client:
    api = CrystalsApi(client)
    result = api.crystals_recommend_natal(natal_crystal_request=request)
    print(result)

TypeScript

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

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

const result = await crystalsRecommendNatal({
  client,
  body: {
      "name": "Arjun Mehta",
      "date": "1985-11-12",
      "time": "06:45",
      "location": "Mumbai"
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "natal_context": {
      "lagna_sign": "Libra",
      "lagna_lord": "Venus",
      "fifth_sign": "Aquarius",
      "fifth_lord": "Saturn",
      "ninth_sign": "Gemini",
      "ninth_lord": "Mercury",
      "yogakaraka": "Saturn",
      "contraindicated_lords": [
        "Jupiter",
        "Moon",
        "... and 2 more items"
      ],
      "ayanamsa": "lahiri"
    },
    "total": 5,
    "crystals": [
      {
        "slug": "diamond",
        "name": "Diamond",
        "colors": [
          "colourless",
          "white",
          "... and 1 more item"
        ],
        "hardness_mohs": 10.0,
        "chakras": [
          "Crown"
        ],
        "element": "Air",
        "zodiac_signs": [
          "Taurus",
          "Libra"
        ],
        "vedic_planet": "Venus",
        "vedic_correspondence": "navaratna",
        "western_planet": "Venus",
        "keywords": [
          "refinement",
          "beauty",
          "... and 3 more items"
        ],
        "healing_physical": "Traditionally linked with the reproductive system and kidneys in Jyotish remedial practice.",
        "healing_emotional": "Associated with refinement, harmony in relationships, and a clear sense of personal worth.",
        "healing_spiritual": "Heera (Vajra) — the primary Navaratna gemstone for Venus (Shukra) in the Phaladeepika gemstone table.",
        "description": "Crystalline carbon (C), the hardest natural mineral at Mohs 10. Heera or Vajra in Sanskrit — the primary Navaratna gemst…",
        "origins": [
          "Botswana",
          "Russia",
          "... and 2 more items"
        ],
        "affirmation": "I welcome beauty, harmony, and refinement into my life.",
        "caution": "Wear only on qualified Jyotish recommendation. Strengthens Venus — not suitable where Venus is a functional malefic for…",
        "match_score": 5,
        "match_reasons": [
          "Lagna lord (Venus) — primary Life Stone"
        ],
        "warnings": [
          "Wear only on qualified Jyotish recommendation. Strengthens Venus — not suitable where Venus is a functional malefic for…"
        ]
      },
      {
        "slug": "clear-quartz",
        "name": "Clear Quartz",
        "colors": [
          "clear",
          "white"
        ],
        "hardness_mohs": 7.0,
        "chakras": [
          "Crown"
        ],
        "element": "All",
        "zodiac_signs": [
          "Aries",
          "Leo"
        ],
        "vedic_planet": "Venus",
        "vedic_correspondence": "uparatna",
        "western_planet": "Sun",
        "keywords": [
          "amplification",
          "clarity",
          "... and 3 more items"
        ],
        "healing_physical": "Amplifies energy of other crystals, supports immune system and overall vitality.",
        "healing_emotional": "Brings mental clarity and helps dissolve confusion.",
        "healing_spiritual": "Known as Sphatik in classical Indian tradition — used for rosaries and as a minor substitute for Diamond (Venus). Harmon…",
        "description": "The most versatile and widely used crystal. Known as Sphatik in Vedic tradition, it is used in temple worship and as a m…",
        "origins": [
          "Brazil",
          "Arkansas (USA)",
          "... and 2 more items"
        ],
        "affirmation": "I am clear, focused, and open to receive.",
        "caution": null,
        "match_score": 4,
        "match_reasons": [
          "Lagna lord (Venus) — primary Life Stone"
        ],
        "warnings": []
      },
      "... and 3 more items"
    ]
  }
}