Numerology API guide

Calculate a Life Path number, a full six-number chart, or a yearly forecast. No birth time or location needed.

Numerology is the easiest domain to ship because it needs no geocoding and no time. A Life Path calculation takes a year, month, and day and returns the Life Path number, every calculation step, a full written interpretation, and karmic debt detection. life path number calculator is among the highest-volume spiritual searches globally.

What you can build

• Life Path calculator pages (the #1 numerology keyword)
• Compatibility features for dating and wellness apps
• Personal Year forecasts that drive January traffic spikes
• Full six-number chart tools with karmic lessons and pinnacles
• Personality quizzes built on name-based Expression and Soul Urge
• Chaldean name readings with compound numbers, plus dual-system (Pythagorean and Chaldean) comparison

Prerequisites

1. A RoxyAPI key. Get your API key.
2. Nothing else. No coordinates, no birth time, no account sync.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

Call the endpoint

The #1 numerology call is Life Path. Pick a language tab and paste.

curl -X POST https://roxyapi.com/api/v2/numerology/life-path \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year": 1990, "month": 7, "day": 15}'

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data, error } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 7, day: 15 },
});
if (error) throw error;

console.log(data.number);            // 5
console.log(data.meaning.title);     // "The Adventurer"
console.log(data.hasKarmicDebt);     // true | false

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

result = roxy.numerology.calculate_life_path(year=1990, month=7, day=15)
print(result['number'])
print(result['meaning']['title'])
print(result['hasKarmicDebt'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$result = $roxy->numerology->calculateLifePath(year: 1990, month: 7, day: 15);
echo $result['number'];
echo $result['meaning']['title'];
echo $result['hasKarmicDebt'] ? 'true' : 'false';

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var result = await roxy.Numerology.LifePath.PostAsync(new() { Year = 1990, Month = 7, Day = 15 });

Console.WriteLine(result!.Number);         // 5
Console.WriteLine(result.Meaning!.Title);  // "The Adventurer"
Console.WriteLine(result.HasKarmicDebt);   // true | false

claude mcp add-json --scope user roxy-numerology '{"type":"http","url":"https://roxyapi.com/mcp/numerology","headers":{"X-API-Key":"YOUR_KEY"}}'

The response includes the number, the calculation breakdown, the type (single or master), karmic debt detection, and a meaning block with title, keywords, strengths, challenges, career guidance, relationship guidance, and spirituality guidance. You never have to write any interpretation text.

Render the result

Skip building the render layer: RoxyNumerologyCard from @roxyapi/ui renders the number, title, calculation breakdown, keywords, and the karmic debt callout from the response, and switches layout with the type prop. Fetch on your server so the key never reaches the browser, then pass the unwrapped data to the component. Want full control of the markup? The response is plain JSON, build whatever you like.

'use client';
import { RoxyNumerologyCard } from '@roxyapi/ui-react';
import type { PostNumerologyLifePathResponse } from '@roxyapi/sdk';

export function LifePathCard({ data }: { data: PostNumerologyLifePathResponse }) {
  return <RoxyNumerologyCard data={data} type="life-path" />;
}

Pass the same component type="expression", type="personal-year", or type="chart" to render the other numerology endpoints with no extra markup. The data you pass is the unwrapped SDK response, not the full { data, error } envelope.

Ship the rest

Full chart, the six-number upsell

POST /numerology/chart returns all core numbers plus additional insights in one call. Give it a full name and birth date, get Life Path, Expression, Soul Urge, Personality, Birth Day, and Maturity, plus karmic lessons, karmic debt in all five positions, the personal year, the four pinnacles (master numbers kept) and four challenges (the Main Challenge runs for life), hidden passion, subconscious self, and the cornerstone, capstone, and first vowel. This is the premium product.

curl -X POST https://roxyapi.com/api/v2/numerology/chart \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fullName": "John William Smith", "year": 1990, "month": 7, "day": 15}'

Compatibility, the dating-app bolt-on

POST /numerology/compatibility accepts either raw numbers per person (if you already calculated them) or full name plus birth date (and the server calculates them for you). Returns an overall score from 50 to 100, a rating label, a score per number pair, strengths, challenges, and advice.

Personal Year, the annual-forecast hook

POST /numerology/personal-year returns the theme, forecast, opportunities, challenges, and advice for the year. The Personal Year turns over on 1 January, so it suits renewal-style content cadence and January traffic spikes. Pass year to forecast another year; it defaults to the current UTC year.

Expression, the name-based differentiator

POST /numerology/expression takes fullName only and returns the number with every letter value listed name by name in calculation. This powers career-coaching, personal-brand, and self-discovery products.

Choose an individual core number

Use the full chart when the screen needs all six numbers. For a focused calculator, request only the number it displays:

Name calculations show the letters actually counted. Do not add phonetic Y-vowel rules or restrict accepted names to ASCII. A name without the letters required for the selected calculation returns a validation error. Keep the calculation breakdown beside the interpretation so readers can distinguish the arithmetic from its traditional meaning.

Chaldean numerology, the second system

POST /numerology/chaldean reads a name in the older Chaldean system, which maps letters 1 to 8 by vibration (the number 9 is never assigned to a letter) and returns the compound number (10 to 52, the Cheiro fadic numbers) alongside the single-digit root and its planetary ruler, reading a longer name name by name as Cheiro does. The compound is the hidden influence behind the name; the root is the outward expression.

curl -X POST https://roxyapi.com/api/v2/numerology/chaldean \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Helen"}'

Three companions complete the system. GET /numerology/compound-number/{number} looks up the classical meaning of any compound number 10 to 52 (the Wheel of Fortune, the Star of the Magi, the Crown of the Magi). POST /numerology/dual returns the Pythagorean and Chaldean name numbers side by side in one call with an agreement flag, so you can show both systems without two round trips. POST /numerology/business-name rates a business or brand name with Chaldean numerology, returning its root, planetary ruler, a business rating, and the industries the number favors.

See the full list at the Numerology API reference.

Ready-made template

The /templates/numerology-starter-app template ships a working Numerology app you can clone, white-label, and deploy. MIT licensed. For the render layer, drop in <roxy-numerology-card> from @roxyapi/ui.

Gotchas

• Master numbers 11, 22, 33 are not reduced. The API handles this, you do not need to post-process. type will be "master" when this applies.
• Karmic debt numbers are 13, 14, 16, 19. hasKarmicDebt flags presence, karmicDebtNumber gives the specific number and karmicDebtMeaning the interpretation. Show this. Users find it fascinating.
• Name fields are case-insensitive. John William Smith and john william smith produce the same Expression number. Pass the birth-certificate name for canonical results.
• Names in any script work. A name in Cyrillic, Greek, Devanagari, Hangul, Chinese, or any other script is converted to Latin letters before it is counted, Cyrillic and Greek as the passport spelling, and accents fold to the base letter. The calculation string shows the letters counted. For a script that does not write its vowels, send the Latin spelling the person uses.
• Compatibility accepts both shapes. Either { lifePath, expression, soulUrge } or { fullName, year, month, day } per person, and the two people may use different shapes.
• Personal Year needs only month and day. year is optional and defaults to the current UTC year. The year turns over on 1 January, not on the birthday. Pass year if you are projecting forward.

What to build next

The quickstart ends with a working HTML Life Path calculator you can double-click into a browser. Numerology pairs well with tarot for wellness apps, see the AI chatbot tutorial for multi-domain conversational patterns. For typed calls, the SDK guide covers compatibility and chart methods.