# Numerology API

> Production-ready Pythagorean numerology API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. 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. Unicode-aware multilingual name handling: Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Belarusian, Hindi, Bengali, Tamil, Japanese, Chinese, Korean, Arabic, Greek, and Hebrew names produce correct Pythagorean numbers via automatic transliteration so accented and non-Latin scripts no longer silently drop letters. 16 endpoints with detailed interpretations optimized for numerology apps, editorial platforms, AI chatbots, wellness platforms, and spiritual services.

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

- Product page: https://roxyapi.com/products/numerology-api
- OpenAPI spec: https://roxyapi.com/api/v2/numerology/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/numerology
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <50ms
- uptime: 99.9%
- endpoints: 16

## Features

- 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
- Global name input support - Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Belarusian, Hindi, Bengali, Tamil, Japanese (Hiragana and Katakana), Chinese, Korean, Arabic, Greek, Hebrew names automatically transliterated to Latin for correct Pythagorean number computation, so José Garcia, Анна, राज, 김민준, and 王明 all produce the same accurate output as their plain ASCII equivalents

## Use Cases

- 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

## Languages

en, de, es, fr, hi, pt, ru, tr

## Endpoints

- `POST /api/v2/numerology/life-path` Calculate Life Path number - Most important numerology calculation
- `POST /api/v2/numerology/expression` Calculate Expression number - Natural talents and life goals
- `POST /api/v2/numerology/bridge` Calculate Bridge Numbers - Harmonize different aspects of personality
- `POST /api/v2/numerology/soul-urge` Calculate Soul Urge number - Inner motivations and desires
- `POST /api/v2/numerology/personality` Calculate Personality number - How others perceive you
- `POST /api/v2/numerology/birth-day` Calculate Birth Day number - Special talents from day of birth
- `POST /api/v2/numerology/maturity` Calculate Maturity number - Who you become in later life
- `POST /api/v2/numerology/karmic-lessons` Analyze Karmic Lessons - Life lessons from missing numbers
- `POST /api/v2/numerology/karmic-debt` Detect Karmic Debt numbers - Past life challenges (13, 14, 16, 19)
- `POST /api/v2/numerology/personal-day` Calculate Personal Day - Daily personalized numerology forecast
- `POST /api/v2/numerology/personal-month` Calculate Personal Month - Monthly numerology forecast
- `POST /api/v2/numerology/personal-year` Calculate Personal Year - Annual cycle and forecast for current year
- `POST /api/v2/numerology/compatibility` Calculate Compatibility - Relationship dynamics between two people
- `POST /api/v2/numerology/chart` Generate Complete Numerology Chart - Full profile analysis
- `GET /api/v2/numerology/meanings/{number}` Get Number Meaning - Interpretation for any number 1-9, 11, 22, 33
- `POST /api/v2/numerology/daily` Get daily numerology number - Number of the Day with interpretation

## Example Response

```
POST /api/v2/numerology/chart
```

```json
{
  "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..."
}
```

## Quick Start

```bash
curl -H "X-API-Key: ${ROXY_API_KEY}" -H "Content-Type: application/json" \
  https://roxyapi.com/api/v2/numerology/...
```

For full request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/numerology/openapi.json.