Add numerology and astrology to your site with one REST API

Numerology and astrology features look simple from the outside: a visitor types a name or a birth date, and gets a reading back. Under the hood they are fiddly. Every tradition counts letters and dates differently, the edge cases are endless (master numbers, karmic debts, leap years, Arabic Abjad values, Vedic vs Western letter maps), and once you ship one calculator, users ask for ten more.

Building and maintaining that engine yourself is rarely worth it. In this guide I will show how to add a whole family of numerology and astrology calculators to any site or app by calling one REST API, so you never host a numerology engine of your own.

I build NumroQ, so I will use it for the examples, but the pattern below applies to any calculator API.

The idea: one endpoint, many calculators

Instead of one route per feature, there is a single calculate endpoint and you pass the tool you want by id:

POST /api/v1/calculator/{tool_id}

You send a small JSON body (a name, a birth date, or both), and you get a structured result back. The list of every available calculator is itself an endpoint, so you never hard-code tool ids:

GET /api/v1/plugin/calculators

That covers Western, Vedic, Chaldean, Jewish and Greek numerology, Islamic Abjad and Ism-e-Azam, Western, Vedic and Chinese astrology, the Matrix of Destiny, tarot and everyday number tools, all through the same shape.

You can grab a free API key from the developer portal to follow along. The full reference lives in the docs.

Example 1: a Life Path number from a birth date

The Life Path number is the classic starting point. Here it is in three languages.

cURL

curl -s -X POST "https://numroq-api-production.up.railway.app/api/v1/calculator/life_path_calculator" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NUMROQ_API_KEY" \
  -d '{"birth_date": "1990-05-15"}'

Python

import os, json, urllib.request

BASE_URL = "https://numroq-api-production.up.railway.app/api/v1"
API_KEY = os.environ["NUMROQ_API_KEY"]

def calculate(tool_id, payload):
    req = urllib.request.Request(
        f"{BASE_URL}/calculator/{tool_id}",
        data=json.dumps(payload).encode(),
        headers={"Content-Type": "application/json", "X-API-Key": API_KEY},
        method="POST",
    )
    with urllib.request.urlopen(req) as res:
        return json.loads(res.read().decode())

print(calculate("life_path_calculator", {"birth_date": "1990-05-15"}))

JavaScript (Node 18+)

const BASE_URL = "https://numroq-api-production.up.railway.app/api/v1";

async function calculate(toolId, payload) {
  const res = await fetch(`${BASE_URL}/calculator/${toolId}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.NUMROQ_API_KEY,
    },
    body: JSON.stringify(payload),
  });
  return res.json();
}

console.log(await calculate("life_path_calculator", { birth_date: "1990-05-15" }));

Example 2: a full numerology report from a name plus a birth date

Because every calculator shares the same shape, going from one number to a full report is just a different tool id and a slightly bigger body:

const report = await calculate("numerology_report", {
  text: "John Michael Smith",
  birth_date: "1990-05-15",
});

The report bundles the core numbers (Life Path, Expression, Soul Urge, Personality, Birthday, Maturity) plus pinnacles, challenges, karmic debts, hidden passion and more. You render the fields you want; the counting and the meanings are done for you.

Example 3: Abjad, for Arabic and Urdu names

Abjad (Arabic letter numerology) is a good example of something you really do not want to reimplement, because the letter values and the spelling variants matter:

const abjad = await calculate("abjad", { text: "محمد" });

Same endpoint, same auth, just a different tool id and Arabic text in.

Keep your key on the server

One thing worth calling out: the API key goes in an X-API-Key header, and it should stay on your server. Call the API from your backend (or a serverless function), cache the result, and pass the finished reading to the browser. That keeps your key private and lets you cache repeat lookups, which matters because a name plus a birth date always produces the same result.

If you are on WordPress and do not want to write any backend code at all, there is a free plugin that embeds any of these calculators with a shortcode and keeps the key server-side for you.

Wrapping up

The pattern is simple and it scales: one calculate endpoint, tool ids you discover at runtime, the same request shape for every tradition, and the key kept on the server. You add one calculator today and every other one is already wired up.

• Docs and full tool reference: https://numroq.com/docs
• Get a free API key: https://dev.numroq.com
• Runnable examples (Python, JavaScript, cURL, Postman): https://github.com/hafizmabs1987-design/numroq-api-examples

If you build something with it, I would love to hear what tradition or calculator you reached for first.