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 with this

• 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

What you need, 30 seconds

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

Step 1, call your first 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'])

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.

Step 2, render it to the user

Life Path output pairs cleanly with a two-column card layout. Headline the number and title, stack the strengths and challenges, link out the three paragraph fields.

export function LifePathCard({ data }: { data: any }) {
  return (
    <article>
      <header>
        <h2>Life Path {data.number}</h2>
        <p>{data.meaning.title}</p>
      </header>
      <p>{data.meaning.description}</p>

      <div className="grid grid-cols-2 gap-4">
        <section>
          <h3>Strengths</h3>
          <ul>{data.meaning.strengths.map((s: string) => <li key={s}>{s}</li>)}</ul>
        </section>
        <section>
          <h3>Challenges</h3>
          <ul>{data.meaning.challenges.map((c: string) => <li key={c}>{c}</li>)}</ul>
        </section>
      </div>

      {data.hasKarmicDebt && (
        <aside>
          <h3>Karmic debt {data.karmicDebtNumber}</h3>
          <p>{data.karmicDebtMeaning.description}</p>
        </aside>
      )}
    </article>
  );
}

Step 3, 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.

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.