New Numerology API

Use case

Gemstone recommendation API for jewelry stores

The gemstone recommendation API from API for Astrology (apiforastrology.com) picks a stone from each customer's own birth chart and names the planet behind the pick.
Get a free API keyTalk to us

Updated

© API for Astrology (apiforastrology.com). "Gemstone stores explained". All rights reserved. Not to be copied or reused.Acme JewellersHello, John DoeYour chart: Virgo risingAlso inFROM YOUR CHARTEmerald ringSet in gold$240WHY THIS STONEFor Mercury, the ruler of yourVirgo rising signFirst wear onWednesdayFingerLittle fingerMetalGoldPeridotGreen tourmalineA traditional choice. No result is promised.Add to cartAdded1

How it works

  1. 1A shopper enters their birth details on a jewelry store's site.
  2. 2The API picks a gemstone from the shopper's chart and says why: the planet it is for, and how that planet was chosen.
  3. 3The product page shows the stone with the day to first wear it, the finger and the metal, and cheaper stones in its place.
POST /v1/reading/section/topic:remedy-life-gemstone?as_of=2026-10-01200 OK
{
  "section": {
    "id": "topic:remedy-life-gemstone"
  },
  "blocks": [
    {
      "selection": {
        "graha": "Mercury",
        "stone": "Emerald",
        "metal": "gold",
        "finger": "little",
        "day": "Wednesday"
      }
    }
  ]
}
The life gemstone suggested for John Doe's chart, the planet it is chosen for, and how it is traditionally worn. Real output for John Doe, born Aug 15, 1990, 10:30 AM, New York.

How to recommend gemstones from a birth chart

Each step is one call, linked to its page in the API reference. Where a card shows values, they are real API output. Planet positions come from NASA JPL planet data (DE440). We check them against NASA JPL Horizons. On 25,571 positions from 1850 to 2149, the Sun and planets agree within 0.001 arc seconds. The Moon agrees within 0.011. An arc second is 1/3,600 of a degree. See how we test accuracy. A practicing astrologer reviews the rules behind these answers. Each rule has an ID in the public rulebook.

  1. 01

    Suggest the life gemstone

    POST /v1/reading/section/topic:remedy-life-gemstone

    The stone of the planet that rules the rising sign, the same for life. The selection object names the planet, the stone, cheaper substitutes, the metal, the finger and the day.

    blocks.0.selection.graha
    "Mercury"
    blocks.0.selection.stone
    "Emerald"
    blocks.0.selection.metal
    "gold"
    blocks.0.selection.finger
    "little"
    blocks.0.selection.day
    "Wednesday"

    Real output for John Doe, born Aug 15, 1990, 10:30 AM, New York.

  2. 02

    Suggest a stone for now

    POST /v1/reading/section/topic:remedy-lucky-gemstone

    The stone of the planet whose main period (mahadasha) is running on the date you send as as_of. It changes when that period ends.

    blocks.0.selection.selected_by
    "running mahadasha lord"
    blocks.0.selection.graha
    "Jupiter"
    blocks.0.selection.stone
    "Yellow sapphire"
    blocks.0.selection.same_as_life_gemstone
    false

    Real output for John Doe, born Aug 15, 1990, 10:30 AM, New York.

  3. 03

    Show the chart behind it

    POST /v1/planets

    The rising sign and where each planet sits, for a "why this stone" panel beside the product. In the example, the rising sign is Virgo. Its ruler is Mercury, which is why step 1 picked emerald.

    ascendant.sign
    "Virgo"
    ascendant.degree_dms
    "19 : 56 : 03"
    ascendant.nakshatra
    "Hast"

    Real output from the example in the API reference.

  4. 04

    Offer a rudraksha too

    POST /v1/reading/section/topic:remedy-rudraksha

    For stores that sell rudraksha (sacred beads): the bead for the running period, with its number of faces (mukhi).

    blocks.0.selection.graha
    "Jupiter"
    blocks.0.selection.mukhi
    5
    blocks.0.selection.deity
    "Kalagni Rudra"

    Real output for John Doe, born Aug 15, 1990, 10:30 AM, New York.

What you send, what you get, what it costs

You sendThe customer's birth date, time and place, and today's date as as_of for the stone for now.
You getThe life gemstone and a stone for now, each with its planet, substitutes, metal, finger and day, plus a rudraksha and the chart behind the pick.
It costsSteps 1, 2 and 4: 1 reading credit each.Step 3: 1 call.

Costs are for a live key, and failed requests are free. The Free plan includes 2,000 calls and 150 reading credits a month.

Step 1 in code: suggest the life gemstone

Send the details as JSON, with your API key in the Authorization header. The other steps work the same way, and each one links to its page in the API reference.

POST /v1/reading/section/topic:remedy-life-gemstone

# John Doe, born Aug 15, 1990, 10:30 AM, New York
curl -X POST "https://apiforastrology.com/api/astrology/v1/reading/section/topic:remedy-life-gemstone?as_of=2026-10-01" \
  -H "Authorization: Bearer $ASTROLOGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":8,"day":15,"hour":10,"minute":30,"second":0,"latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'

Tips for going live

  • Map the selection fields to your catalog. The stone and its substitutes go to products, the metal to the setting, and the finger to your ring size guide.
  • Show the notes field beside the stone. Where tradition adds a caution, such as a planet that is already strong in the chart, it comes back there. The stone is never hidden.
  • The life gemstone needs an accurate birth time, because the rising sign changes about every two hours.
  • Send today's date as as_of for the stone for now, so it matches the period running when the customer shops.
  • Never promise results. Describe a stone as a traditional choice for a planet, not as a cure, a treatment or a guarantee.
A woman choosing colorful gemstones at a market table

What it costs

A jewelry store showing 1,000 shoppers a month their life gemstone and their stone for now uses 2,000 reading credits. Growth.

Every plan can call every endpoint: calls for calculations, reading credits for written readings. Test keys are free on every plan, with 1,000 calls a month. Paid plans start at $29 a month, and failed requests are free.

See pricing

Try it free

See an answer first

  • Free kundli

    Your Vedic birth chart: the rising sign and all nine planets, with sign, house and nakshatra.

    Make my kundli
All free tools

Features used here

Read next

Common questions

All questions
Why does the API suggest two different stones?

The life gemstone comes from the ruler of the rising sign and never changes. The stone for now (the lucky gemstone) follows the planet whose main period is running, so it changes when that period ends. When the two are the same stone, same_as_life_gemstone is true.

Read the rule
How do we explain the pick to a shopper?

Use the selection object. selected_by says how the planet was chosen, such as ascendant lord, and for the life gemstone, ascendant names the rising sign. A line like "Emerald, for Mercury, the ruler of your Virgo rising sign" comes straight from those fields.

Read the rule
Does the API give cheaper alternatives?

Yes. substitutes lists the stones tradition accepts in place of the main one, such as peridot or green tourmaline for emerald. So you can offer more than one price point for the same suggestion.

About the remedies API
Will the API ever warn against a stone?

It never hides a suggestion. Where tradition adds a caution, the notes field says so, for example when the planet is already strong in the chart. Show those notes on the product page, so the customer sees them before buying.

Read the rule
Does the customer need an exact birth time?

For the life gemstone, yes: it comes from the rising sign, which changes about every two hours. The stone for now comes from the running period, which depends on the Moon and is less sensitive to the time. Still, an exact time is best.

What the rising sign (lagna) is
Can our store say a gemstone will heal or bring luck?

No. In our terms, gemstones are a traditional practice with no promised effect. Nothing from the API may be sold as medical, legal, financial or psychological advice. The claims on your product pages are yours to stand behind.

Read the astrology disclaimer

Astrology API

Start with a free test key

Create an account and a test key, then try each step above. Need more than the largest plan? Write to us.

Get a free API keyOpen the API reference

Your first answer

John Doe, New York

POST /v1/planets200 OK
  • RisingVirgoHast
  • SunCancerAshlesha
  • MoonTaurusMrigashira
  • MarsAriesKrittika

Real API output. A free test key gets the same answer.

  1. 01

    Test key: 1,000 test calls a month to build with

  2. 02

    Free plan: 2,000 live calls a month, no card needed

  3. 03

    Open rules: every rule is published, so you can check any answer