RoxyAPI

Menu

  1. Docs
  3. Domain Guides
  5. Numerology

Numerology

Numerology derives personality insights and predictions from numbers in your birth date and name. It is simpler than astrology (no birth time or location needed) which makes it great for low-friction app features. Your users care about this for personality quizzes, compatibility checking, and yearly forecasts.

New to fetch()? The Western Astrology guide has an annotated example explaining every line of an API call.

What you can build

  • Life Path calculators — the most popular numerology feature, needs only a birth date
  • Compatibility tools — compare two people by their core numbers
  • Personal Year forecasts — yearly themes and predictions
  • Complete profile generators — Life Path, Expression, Soul Urge, Personality in one view

Which endpoints to call

Life Path number

The most common call. Only needs a birth date:

const response = await fetch('https://roxyapi.com/api/v2/numerology/life-path', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({ year: 1990, month: 7, day: 15 })
});
const lifePath = await response.json();

Response:

{
  "number": 5,
  "calculation": "Month: 7, Day: 15 > 6, Year: 1990 > 1 > 7+6+1=14 > 5",
  "type": "single",
  "hasKarmicDebt": true,
  "karmicDebtNumber": 14,
  "karmicDebtMeaning": {
    "description": "Karmic Debt of Abuse of Freedom",
    "challenge": "Past life misuse of personal freedom...",
    "resolution": "Learn balance, moderation, and responsible use of freedom."
  },
  "meaning": {
    "title": "The Adventurer",
    "keywords": ["freedom", "adventure", "change", "versatility"],
    "description": "The number 5 is curiosity and the need for variety...",
    "strengths": ["Curious: The opposite of tunnel vision...", "Adaptable: ...", "Social: ..."],
    "challenges": ["Non-committal: ...", "Unreliable: ..."],
    "career": "Life Path 5 thrives in careers that offer freedom, variety...",
    "relationships": "Life Path 5 individuals are exciting, charming partners...",
    "spirituality": "Five is the rebel, the traveler, the agent of change..."
  }
}

Which fields to show your users: number is the headline (Life Path 5). meaning.title ("The Adventurer") is the catchy label. meaning.description is the personality profile. meaning.strengths and meaning.challenges are arrays of detailed trait descriptions — great for UI cards. meaning.career, meaning.relationships, and meaning.spirituality are paragraph-length interpretations for deeper content. hasKarmicDebt and karmicDebtMeaning are engagement hooks — users love discovering hidden patterns. calculation shows the math so users trust the result.

Expression number

Calculated from the full birth name. Reveals natural talents and abilities:

const response = await fetch('https://roxyapi.com/api/v2/numerology/expression', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({ fullName: 'John William Smith' })
});
const expression = await response.json();
// expression.number, expression.meaning.title, expression.meaning.description

Soul Urge number

Inner motivations and desires. Also uses full birth name (vowels only):

const response = await fetch('https://roxyapi.com/api/v2/numerology/soul-urge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({ fullName: 'John William Smith' })
});
const soulUrge = await response.json();

Compatibility

Compatibility takes pre-calculated numbers, not raw birth data. Call Life Path, Expression, and Soul Urge first for each person, then pass the numbers:

// Step 1: Calculate core numbers for each person
const p1LifePath = await fetch('https://roxyapi.com/api/v2/numerology/life-path', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({ year: 1990, month: 7, day: 15 })
}).then(r => r.json());

const p1Expression = await fetch('https://roxyapi.com/api/v2/numerology/expression', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({ fullName: 'John William Smith' })
}).then(r => r.json());

const p1SoulUrge = await fetch('https://roxyapi.com/api/v2/numerology/soul-urge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({ fullName: 'John William Smith' })
}).then(r => r.json());

// (Repeat for person 2)

// Step 2: Pass the numbers to compatibility
const response = await fetch('https://roxyapi.com/api/v2/numerology/compatibility', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    person1: { lifePath: p1LifePath.number, expression: p1Expression.number, soulUrge: p1SoulUrge.number },
    person2: { lifePath: 8, expression: 1, soulUrge: 4 }
  })
});
const compat = await response.json();
// compat.overallScore (0-100), compat.rating, compat.lifePath.compatibility, compat.strengths

Which fields to show your users: overallScore (0-100) is the headline. rating is a word label (Poor/Fair/Good/Excellent/Exceptional). lifePath, expression, and soulUrge each have their own compatibility score and description. strengths and challenges are arrays.

Complete chart

Returns all core numbers in one call. Needs both birth date and full name:

const response = await fetch('https://roxyapi.com/api/v2/numerology/chart', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    year: 1990, month: 7, day: 15,
    fullName: 'John William Smith'
  })
});
const chart = await response.json();
// chart.coreNumbers.lifePath, chart.coreNumbers.expression, chart.coreNumbers.soulUrge, etc.

Personal Year

The theme for the current year. Great for yearly forecast features:

const response = await fetch('https://roxyapi.com/api/v2/numerology/personal-year', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({ year: 1990, month: 7, day: 15 })
});
const personalYear = await response.json();
// personalYear.number, personalYear.meaning.title, personalYear.meaning.description

Key concepts

  • Life Path — calculated from birth date. The most important number in numerology, like your sun sign in astrology. Reveals your core life purpose.
  • Expression (Destiny) — calculated from full birth name using Pythagorean letter-to-number mapping. Shows natural talents and abilities.
  • Soul Urge (Heart's Desire) — calculated from vowels in birth name. Reveals inner motivations and what truly drives someone.
  • Personality — calculated from consonants in birth name. Shows how others perceive you.
  • Personal Year — calculated from birth date + current year. Reveals the theme for the current year (1-9 cycle).
  • Karmic Debt — numbers 13, 14, 16, 19 that appear during calculation. Indicate lessons carried from past lives. Users find this fascinating.
  • Master Numbers — 11, 22, 33 are not reduced to single digits. They carry amplified energy and special significance.

No domain knowledge needed. All responses include complete interpretations.

Full API reference

See all Numerology endpoints in the API Reference.