Numerology API

Ship a numerology app your users will love. This week.

<50mslatency
99.9%uptime
16endpoints

Start building in seconds

Terminal
npm install @roxyapi/sdk
import Roxy from '@roxyapi/sdk'

const roxy = new Roxy({ apiKey: 'your-key' })
const data = await roxy.numerology.get(/* ... */)
SDK docs

Want to ship faster? Clone a free starter app and go from zero to production in 30 minutes.

Building with Cursor, Claude Code, or Bolt? Use our AI prompts to generate a complete app in minutes.

POST /api/v2/numerology/chart
{
  "profile": {
    "name": "John William Smith",
    "birthdate": "1990-07-15"
  },
  "coreNumbers": {
    "lifePath": {
      "number": 5,
      "calculation": "Month: 7, Day: 15 > 6, Year: 1990 > 1 > 7+6+1=14 > 5",
      "type": "single",
      "hasKarmicDebt": true,
      "karmicDebtNumber": 14,
      "meaning": {
        "title": "The Adventurer",
        "keywords": [
          "freedom",
          "adventure",
          "change",
          "versatility"
        ]
      }
    },
    "expression": {
      "number": 6,
      "type": "single",
      "meaning": {
        "title": "The Nurturer",
        "keywords": [
          "love",
          "harmony",
          "responsibility"
        ]
      }
    },
    "soulUrge": {
      "number": 7,
      "meaning": {
        "title": "The Seeker"
      }
    },
    "personality": {
      "number": 8,
      "meaning": {
        "title": "The Powerhouse"
      }
    },
    "birthDay": {
      "number": 6,
      "calculation": "15 > 6",
      "type": "single",
      "hasKarmicDebt": false
    },
    "maturity": {
      "number": 11,
      "type": "master",
      "meaning": {
        "title": "The Master Intuitive"
      }
    }
  },
  "additionalInsights": {
    "karmicLessons": {
      "missingNumbers": [
        7
      ],
      "lessons": [
        {
          "number": 7,
          "lesson": "Learn introspection, spirituality, and trust"
        }
      ]
    },
    "karmicDebt": {
      "hasKarmicDebt": true,
      "debtNumbers": [
        14
      ],
      "meanings": [
        {
          "number": 14,
          "description": "Karmic Debt of Abuse of Freedom",
          "challenge": "Past life misuse of personal freedom...",
          "resolution": "Learn balance, moderation, and responsible use of freedom..."
        }
      ]
    },
    "personalYear": {
      "personalYear": 5,
      "cycle": "Year 5 of 9",
      "theme": "Freedom and Change",
      "personalMonth": {
        "personalMonth": 9,
        "theme": "Completion and Release",
        "focus": "Wrap up loose ends, let go of what no longer serves you..."
      }
    },
    "pinnacles": [
      {
        "position": 1,
        "number": 4,
        "startAge": 0,
        "endAge": 31,
        "meaning": {
          "title": "Foundation and Discipline"
        }
      },
      {
        "position": 2,
        "number": 7,
        "startAge": 32,
        "endAge": 40,
        "meaning": {
          "title": "Wisdom and Introspection"
        }
      },
      {
        "position": 3,
        "number": 11,
        "startAge": 41,
        "endAge": 49,
        "meaning": {
          "title": "Illumination and Inspiration"
        }
      },
      {
        "position": 4,
        "number": 8,
        "startAge": 50,
        "endAge": null,
        "meaning": {
          "title": "Achievement and Authority"
        }
      }
    ],
    "challenges": [
      {
        "position": 1,
        "number": 1,
        "startAge": 0,
        "endAge": 31,
        "meaning": {
          "title": "The Independence Challenge"
        }
      },
      {
        "position": 2,
        "number": 5,
        "startAge": 32,
        "endAge": 40,
        "meaning": {
          "title": "The Freedom Challenge"
        }
      }
    ],
    "hiddenPassion": {
      "number": 1,
      "count": 3,
      "allPassions": [
        1,
        9
      ],
      "title": "The Drive to Lead"
    },
    "subconsciousSelf": {
      "number": 8,
      "uniqueNumbers": [
        1,
        2,
        3,
        4,
        5,
        6,
        8,
        9
      ],
      "title": "Deeply Resourceful"
    },
    "nameLetters": {
      "cornerstone": {
        "letter": "J",
        "number": 1,
        "meaning": "You approach new situations with independence and determination..."
      },
      "capstone": {
        "letter": "N",
        "number": 5
      },
      "firstVowel": {
        "letter": "O"
      }
    }
  },
  "birthDayProfile": {
    "day": 15,
    "reducesTo": 6,
    "title": "The Magnetic Healer",
    "keywords": [
      "magnetism",
      "artistic talent",
      "responsibility",
      "compassion"
    ]
  },
  "maturityStatus": {
    "isActive": true,
    "currentAge": 36,
    "activationRange": "35-40"
  },
  "luckyAssociations": {
    "colors": [
      "Green",
      "Turquoise",
      "Light Brown"
    ],
    "gemstones": [
      "Emerald",
      "Aquamarine",
      "Diamond"
    ],
    "day": "Wednesday",
    "element": "Air",
    "rulingPlanet": "Mercury",
    "compatibleNumbers": [
      1,
      3,
      5,
      7,
      9
    ],
    "incompatibleNumbers": [
      2,
      4,
      6
    ]
  },
  "summary": "Your numerology chart reveals a Life Path 5 (The Adventurer), indicating freedom, adventure, change energy..."
}

Structured JSON with documented fields. Not hallucinated text. See all 16 endpoints

Works with your stack

Claude CodeCursorChatGPTWindsurfVS Code CopilotOpenAI AgentsGeminiLangChainCrewAIVercel AI SDK

Production-ready Pythagorean numerology API + MCP for AI agents and developers. Calculate life path, expression, soul urge, personality, and maturity numbers. Pinnacle and Challenge life phase timing with meanings. Hidden Passion, Subconscious Self, and Cornerstone/Capstone name analysis. Birth day 1-31 profiles, lucky associations (colors, gemstones, planets), personal year and month forecasts, relationship compatibility, karmic debt and lessons. 16 endpoints with detailed interpretations optimized for numerology apps, editorial platforms, AI chatbots, wellness platforms, and spiritual services.

Multi-language API responses

EnglishDeutschEspanolFrancaisHindiPortuguesRusskiyTurkce

Free Starter Apps for Numerology

Clone. Edit. Ship. Free and open source by Team Roxy.

AI astrology chatbot template with MCP integration, horoscope, tarot, numerology, birth chart, and Vedic astrology powered by RoxyAPI

AI Astrology Chatbot

Web App / Open Source30 min

AI chatbot with real readings across all spiritual domains. Not hallucinations.

AstrologyVedicTarotNumerologyCrystalsDreamsI-ChingAngel Numbers
Numerology calculator template with Life Path number, Expression number, Soul Urge number, compatibility score, and Personal Year forecast

Numerology Calculator App

Mobile App / Open Source30 min

Life Path. Expression. Soul Urge. Every core number.

NumerologyLife PathCompatibility

Browse all templates or use AI prompts to generate a custom app.

Key Features

Everything you need from our Numerology API, built for production:

Life Path number reveals life purpose and destiny from birth date - detects master numbers 11, 22, 33 and karmic debt 13, 14, 16, 19

Expression (Destiny) and Soul Urge numbers from full birth name - uncover natural talents, inner motivations, and spiritual mission

Relationship compatibility scoring (0-100) - weighted analysis of Life Path, Expression, Soul Urge with strengths, challenges, and advice for couples

Personal Year cycles (1-9) - annual forecasts with themes, opportunities, challenges, and strategic guidance for year-ahead planning

Karmic Lessons analysis - identify missing numbers in birth name revealing underdeveloped traits and growth opportunities

Complete numerology chart - all core numbers, pinnacles, challenges, hidden passion, subconscious self, name analysis, lucky associations, karmic analysis, and yearly forecast in a single API call

Pinnacle and Challenge numbers - four life phases with calculated age ranges, meanings, opportunities, and obstacles for predictive life timeline analysis

Birth Day profiles (1-31) - unique personality, career, and relationship insights per calendar day, not just the reduced single digit

Hidden Passion, Subconscious Self, Cornerstone, Capstone, and First Vowel analysis - deep name letter profiling for editorial-grade readings

Lucky associations per Life Path - colors, gemstones, ruling planet, element, compatible and incompatible numbers for personalized lifestyle content

Personal Year, Month, and Day forecasts - annual, monthly, and daily personalized themes and guidance for year-ahead, month-ahead, and daily planning

Bridge Numbers - reveal the gap between Life Path and Expression, Expression and Personality, Expression and Soul Urge with actionable advice for harmonizing different aspects of self

Maturity Number with activation status - reveals emerging life purpose around age 35-40, accepts raw name and birthdate or pre-calculated numbers

Compatibility accepts raw name and birthdate inputs - no pre-calculation needed, supports mixed mode (numbers for one person, raw inputs for the other)

Number meanings endpoint - fetch detailed 300-500 word interpretations for any number (1-9, 11, 22, 33) across all contexts

AI-optimized responses - structured JSON with keywords, descriptions, and context perfect for chatbot integration and LLM consumption

Pure mathematics - zero external dependencies, lightning-fast calculations under 20ms, no rate limiting by algorithm complexity

Proven accuracy - verified against authoritative Pythagorean numerology standards with step-by-step calculation strings for full transparency

Multi-language responses in 8 languages (EN, DE, ES, FR, HI, PT, RU, TR) via ?lang= query parameter

All 16 Endpoints

Click any endpoint to view detailed documentation, parameters, and response examples.

Calculate Life Path number - Most important numerology calculation

Calculate your Life Path number from your birth date using Pythagorean numerology. This is the most significant number in your numerology chart, revealing your life purpose, natural talents, and destiny path. Automatically detects Master Numbers (11, 22, 33) and Karmic Debt numbers (13, 14, 16, 19). Returns comprehensive interpretation including personality traits, strengths, challenges, career guidance, relationship compatibility, and spiritual insights. Perfect for numerology apps, birth chart calculators, life purpose discovery tools, personal development platforms, and astrology services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.

Calculate Expression number - Natural talents and life goals

Calculate your Expression (Destiny) number from your full birth name using Pythagorean numerology. This number reveals your natural talents, abilities, and life goals. It shows what you came here to do and what tools you have to accomplish your life purpose. Returns comprehensive interpretation including personality traits, career paths, relationship dynamics, and spiritual insights. Automatically detects Master Numbers (11, 22, 33). Perfect for name numerology apps, career guidance tools, personal development platforms, and talent assessment services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.

Calculate Bridge Numbers - Harmonize different aspects of personality

Calculate three Bridge Numbers that reveal the adjustments needed to create harmony between different aspects of your numerology profile. Bridge Numbers are the absolute difference between pairs of core numbers: Life Path and Expression, Expression and Personality, Expression and Soul Urge. A Bridge of 0 means the two aspects are already aligned. Higher bridges (1 to 8) indicate greater tension and provide specific guidance on what changes to make. Bridge Numbers are essential for personal development, coaching applications, self-improvement platforms, and AI-powered personality analysis tools. Requires both a full birth name and birth date to calculate all four core numbers (Life Path, Expression, Soul Urge, Personality) internally before deriving the bridges.

Calculate Soul Urge number - Inner motivations and desires

Calculate your Soul Urge (Heart Desire) number from the vowels in your birth name using Pythagorean numerology. This number reveals your innermost desires, motivations, and what your soul truly wants to experience. It shows what drives you from within, your emotional needs, and what brings you fulfillment. Returns comprehensive interpretation including personality traits, emotional needs, relationship desires, and spiritual longings. Automatically detects Master Numbers (11, 22, 33). Perfect for self-discovery apps, emotional intelligence tools, relationship counseling platforms, and personal development services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.

Calculate Personality number - How others perceive you

Calculate your Personality number from the consonants in your birth name using Pythagorean numerology. This number reveals how others perceive you, your outer personality, and first impressions you make. It represents the mask you show the world and your social persona. Returns comprehensive interpretation including public image, social dynamics, professional presence, and relationship first impressions. Automatically detects Master Numbers (11, 22, 33). Perfect for personal branding apps, social skills training, professional development platforms, and communication coaching services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.

Calculate Birth Day number - Special talents from day of birth

Calculate your Birth Day number from the day you were born (1-31) using Pythagorean numerology. This number reveals special talents and abilities you possess from birth. It shows natural gifts that can help you achieve your life purpose. Returns comprehensive interpretation including innate talents, natural abilities, career advantages, and how to leverage your special gifts. Automatically detects Master Numbers (11, 22) and reduces double-digit days. Perfect for talent discovery apps, career counseling platforms, personal development services, and skill assessment tools. Get detailed 300-500 word meanings for all numbers 1-9, 11, and 22.

Calculate Maturity number - Who you become in later life

Calculate your Maturity (Realization) number by adding Life Path and Expression numbers using Pythagorean numerology. This number reveals who you become in the second half of life, typically manifesting after age 35-40. It shows the ultimate goal of personal development and mature self-expression. Returns comprehensive interpretation including life transformation, mature personality, later-life purpose, and wisdom development. Automatically detects Master Numbers (11, 22, 33). Perfect for life coaching apps, midlife guidance platforms, personal development services, and aging wisdom tools. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.

Analyze Karmic Lessons - Life lessons from missing numbers

Analyze your Karmic Lessons from your birth name using Pythagorean numerology. Karmic lessons are indicated by numbers missing from your name (numbers 1-9 that do not appear). These represent challenges you came to learn and skills you need to develop in this lifetime. Returns comprehensive analysis including missing numbers, specific lessons for each, challenges to overcome, and practical guidance for development. Perfect for spiritual growth apps, personal development platforms, life coaching services, and self-improvement tools. Get detailed lesson descriptions, development strategies, and practical exercises for each missing number.

Detect Karmic Debt numbers - Past life challenges (13, 14, 16, 19)

Check for Karmic Debt numbers (13, 14, 16, 19) in Life Path, Expression, Soul Urge, or Personality calculations using Pythagorean numerology. Karmic debt indicates challenges carried from past lives that must be resolved in this lifetime. These numbers appear during reduction and represent specific lessons and tests. Returns comprehensive analysis including debt descriptions, challenges to overcome, and resolution guidance. Perfect for spiritual growth apps, karmic astrology platforms, past life exploration services, and personal transformation tools. Get detailed meanings for all four karmic debt numbers with practical resolution strategies.

Calculate Personal Day - Daily personalized numerology forecast

Calculate your Personal Day number from birth month, day, and a target date. Personal Day is the most granular cycle in Pythagorean numerology, revealing the specific energy and theme for a single calendar day personalized to you. Unlike generic daily numbers, this is based on YOUR birth data combined with the calendar date. Returns the daily theme, actionable guidance, and parent month and year context. Perfect for daily push notifications, morning briefings, calendar widget integrations, daily content generation, and life coaching tools.

Calculate Personal Month - Monthly numerology forecast

Calculate your Personal Month number from birth month, day, and a target year and month. Personal Month reveals the specific theme and energy influencing each calendar month within your Personal Year cycle. Returns the monthly theme, practical focus guidance, and the parent Personal Year context. Perfect for monthly forecast features, push notification content, calendar integrations, editorial monthly columns, and life coaching tools.

Calculate Personal Year - Annual cycle and forecast for current year

Calculate your Personal Year number from your birth month, day, and current year using Pythagorean numerology. Personal Year runs in 9-year cycles (1-9) and reveals the theme, opportunities, and challenges for the current year. Each year has a specific energy and lessons. Returns comprehensive annual forecast including year theme, opportunities, challenges, and actionable advice. Perfect for yearly planning apps, life coaching platforms, astrology services, and personal development tools. Get detailed forecasts for all 9 Personal Year cycles with practical guidance.

Calculate Compatibility - Relationship dynamics between two people

Calculate numerology compatibility between two people using Pythagorean numerology. Accepts two input modes per person: pre-calculated Life Path, Expression, and Soul Urge numbers, or raw name and birthdate for automatic calculation. You can mix modes across persons (e.g. numbers for person1, raw inputs for person2). Provides comprehensive relationship analysis with overall compatibility score (0-100), individual aspect compatibility (Life Path 50% weight, Expression 30%, Soul Urge 20%), relationship strengths, challenges, and practical advice. Uses detailed compatibility matrix for all number combinations. Perfect for dating apps, relationship counseling platforms, matchmaking services, and compatibility tools. Get actionable insights for improving relationship dynamics.

Generate Complete Numerology Chart - Full profile analysis

Generate a comprehensive numerology chart combining all major calculations: Life Path, Expression, Soul Urge, Personality, Birth Day, Maturity, Karmic Lessons, Karmic Debt, and Personal Year. This single endpoint provides everything needed for a full numerology reading. Returns detailed interpretations for all numbers, karmic analysis, yearly forecast, and holistic summary. Perfect for numerology apps, complete reading services, birth chart generators, and comprehensive analysis tools. Save multiple API calls by getting the full chart in one request. Ideal for generating PDF reports or detailed user profiles.

Get Number Meaning - Interpretation for any number 1-9, 11, 22, 33

Get the complete meaning and interpretation for any numerology number (1-9, 11, 22, 33) using Pythagorean numerology. Returns comprehensive description including archetype title, keywords, personality traits, strengths, weaknesses, career guidance, relationship dynamics, and spiritual insights. Master numbers (11, 22, 33) include amplified meanings with their reduced base number. Perfect for numerology reference tools, educational apps, quick lookups, and building custom numerology calculators. Get detailed 300-500 word expert-written meanings for all 12 valid numerology numbers.

Get daily numerology number - Number of the Day with interpretation

Receive a daily numerology number (1-9, 11, 22, 33) for guidance and reflection. Uses seeded randomness so the same seed gets the same number on the same date, perfect for "Number of the Day" features in numerology apps, wellness platforms, and daily guidance tools. Returns the number with full interpretation including archetype, keywords, strengths, challenges, career, relationships, and spiritual insights. Ideal for daily push notifications, morning briefings, and personalized numerology experiences.

What You Can Build with Numerology API

Real-world applications and use cases for integrating Numerology API into your projects:

AI chatbots and assistants - integrate numerology readings into conversational AI, ChatGPT plugins, and virtual spiritual advisors with structured responses

Dating and relationship apps - add compatibility scoring to matchmaking algorithms, display Life Path synastry on profiles, show partnership potential scores

Personalized wellness platforms - generate automated numerology reports, birth chart PDFs, and daily/yearly guidance for meditation and self-discovery apps

Life coaching and therapy tools - support client sessions with Personal Year forecasts, karmic lesson identification, and life purpose clarity from Life Path analysis

Content generation systems - power horoscope-style content, numerology blog posts, and personalized email campaigns with accurate calculations and rich interpretations

Spiritual marketplaces and consultation services - enable quick numerology readings, tiered report generation (basic to premium), and automated client onboarding with full chart analysis

What developers are saying

DM

Dhani M.

Indie App Developer

Shipped an astrology app in 3 days. Birth charts, nakshatras, KP cusps, significators. I verified the Lahiri ayanamsha values independently and they are spot on. One API key for all of it.

Email feedback
TH

Tom H.

Senior Developer

The OpenAPI spec is the most complete I have seen in this space. Generated a type-safe TypeScript client from it in seconds. Every field has descriptions and examples. Production-grade documentation.

Email feedback
CW

Chris W.

Backend Engineer

Response times consistently under 50ms for numerology and tarot endpoints. The API returns structured JSON with every field documented. Integrated it into our platform in an afternoon.

Email feedback

Getting Started with Numerology API

From zero to production in 3 steps. No signup required for testing.

3 Steps to Ship

1Install the SDKnpm i @roxyapi/sdk
2Get your API keyView Plans
3Make your first callView Docs

Agent-Ready Infrastructure

MCP

The only MCP server covering 10 spiritual domains under one key

  • MCP server — 16 tools auto-discovered by Claude, ChatGPT, Cursor
  • llms.txt — AI-native documentation for code generation
  • AGENTS.md — Included in SDK for GitHub Copilot, Windsurf, Cline

Start using Numerology API today.

Ship a numerology app your users will love. This week.

All 10 domains included with every plan. 16+ endpoints, MCP server, SDK, and starters.

Plans from $39/mo — thats $3.90 per domain. No credit card required for testing.

View Pricing & Get API Key