Numerology API, what to build and how to call it

Calculate a Life Path number, a full six-number chart, or a yearly forecast in under 10 minutes. 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 a 1000+ word personality interpretation with 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

Prerequisites

1. A Roxy API key. Get one on the pricing page.
2. Nothing else. No coordinates, no birth time, no account sync.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require 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 } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 7, day: 15 },
});

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';

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, personal year, pinnacles, challenges, hidden passion, and subconscious self. 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 overall score 0 to 100, a rating label, strengths, challenges, and advice.

Personal Year, the annual-forecast hook

POST /numerology/personal-year returns the theme for the current year with keywords and advice. Great for renewal-style content cadence and January traffic spikes. Pass year optionally to forecast future years.

Expression, the name-based differentiator

POST /numerology/expression takes fullName only and returns the number derived from Pythagorean letter-to-number mapping. This powers career-coaching, personal-brand, and self-discovery products.

See the full list at the Numerology API reference.

Ready-made starter

The /starters/numerology-starter-app starter ships a working Numerology app you can clone, white-label, and deploy in 30 minutes. 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.
• Compatibility accepts both shapes. Either { lifePath, expression, soulUrge } or { fullName, year, month, day } per person. Pick one and stick to it.
• Personal Year needs only month and day. year is optional and defaults to the current calendar year. Pass it 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.