Numerology API

#What the Numerology API does

The Numerology API provides 10 specialized endpoints for professional numerological analysis: calculate all core numbers from a birth date and full name, retrieve individual number readings with AI-powered interpretations, and generate personal cycle predictions for days, months, and years. Every calculation follows the Pythagorean numerology system with proper handling of master numbers (11, 22, 33).

#The Pythagorean numerology system

Pythagorean numerology (also called Western or modern numerology) is the most widely used system. It maps each letter of the alphabet to a digit from 1 to 9:

To calculate a number, each letter is converted to its digit, the digits are summed, and the result is repeatedly reduced until a single digit (1-9) is reached — unless a master number appears during the reduction process.

#Master numbers: 11, 22, 33

Master numbers are double-digit numbers that carry amplified spiritual significance. When the reduction process produces 11, 22, or 33, the number is not reduced further:

• 11 — The Master Intuitive: Heightened intuition, spiritual insight, and visionary leadership. Combines the qualities of 1 (leadership) doubled with 2 (cooperation).
• 22 — The Master Builder: Ability to turn grand visions into reality. Merges the idealism of 11 with the practical power of 4.
• 33 — The Master Teacher: Selfless devotion to uplifting humanity. Combines the vision of 11 and the building capacity of 22 through compassion (6).

#How each number is calculated

#Life Path Number

Derived from birth date. Each component (month, day, year) is reduced individually, then the three results are summed and reduced to a single digit or master number.

# Example: March 15, 1990
Month: 0 + 3 = 3
Day:   1 + 5 = 6
Year:  1 + 9 + 9 + 0 = 19 -> 1 + 9 = 10 -> 1 + 0 = 1
Total: 3 + 6 + 1 = 10 -> 1 + 0 = 1
Life Path = 1

#Expression (Destiny) Number

Derived from all letters of the full birth name. Each letter is mapped to its Pythagorean value, summed, and reduced.

#Soul Urge (Heart's Desire) Number

Derived from the vowels only (A, E, I, O, U) in the full name. Represents inner motivations and what truly drives you.

#Personality Number

Derived from the consonants only in the full name. Represents the outer persona and how others perceive you.

#Challenge Numbers

Four challenge numbers are derived from the birth date. They represent obstacles to overcome during different life phases:

• First Challenge: Difference between month and day digits
• Second Challenge: Difference between day and year digits
• Third Challenge: Difference between first and second challenges
• Fourth Challenge: Difference between month and year digits

#Subconscious Self Number

Counts how many of the digits 1-9 appear in the full name. The total number of unique digits present reveals your instinctive response in times of crisis.

#Personal cycles: day, month, year

Numerology maps personal time cycles based on the birth date. Each cycle carries a specific vibration that influences energy, opportunities, and focus areas:

• Personal Year: Calculated from birth month + birth day + current calendar year. A 9-year cycle where each year has a theme (1=new beginnings, 9=completion).
• Personal Month: Personal year number + calendar month. Provides monthly focus within the yearly theme.
• Personal Day: Personal month number + calendar day. Daily energy and optimal activities.

#Endpoints at a glance

#Quick start examples

#Get all numbers at once

curl -X POST "https://api.yeb.to/v1/numerology/numerological-numbers" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "birth_date": "1990-03-15",
    "full_name": "John Michael Smith"
  }'

#Life path number only

curl -X POST "https://api.yeb.to/v1/numerology/lifepath-number" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"birth_date": "1990-03-15"}'

#Daily prediction

curl -X POST "https://api.yeb.to/v1/numerology/personal-day-prediction" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "birth_date": "1990-03-15",
    "date": "2026-02-20"
  }'

#Key parameters explained

#Reading & handling responses

Every endpoint returns a consistent structure with two main objects:

• computed_data — The raw numerological calculations (numbers, types). Use this for your own logic or display.
• reading — AI-generated interpretation with meanings, strengths, challenges, and advice. Ready to display to end users.

#Error responses

{ "error": "birth_date is required", "code": 422 }

{ "error": "Invalid API key", "code": 401 }

• 401: Invalid or missing API key
• 422: Missing required parameters or invalid format (e.g. bad date format)
• 429: Rate limit exceeded (20 req/s)
• 402: Insufficient credits
• 500: Server error (retry with exponential backoff)

#Real-world use cases

#Horoscope & spiritual apps

Challenge: Provide personalized numerology readings alongside astrology content
Solution: Use numerological-numbers for the full profile on sign-up, then personal-day-prediction for daily content

#Dating & compatibility apps

Challenge: Add a numerology-based compatibility score
Solution: Compare life path, expression, and soul urge numbers between two users to generate a compatibility analysis

#Wellness & self-improvement

Challenge: Offer personalized daily guidance
Solution: Use personal-day-prediction for daily tips, personal-month-prediction for monthly goals, and challenge-numbers for growth areas

#Baby naming & branding tools

Challenge: Analyze the numerological significance of potential names
Solution: Use expression-number, soul-urge-number, and personality-number to evaluate how a name’s vibration aligns with desired qualities

#Best practices

1. Use numerological-numbers for profiles: Fetch all numbers in one call instead of making 6+ separate requests. More efficient and cheaper.
2. Use birth name: For the most accurate readings, use the full name given at birth (including middle names), not nicknames or married names.
3. Cache static readings: Life path, expression, soul urge, and personality numbers never change. Cache them per user and only refresh personal cycle predictions.
4. Date format matters: Always use YYYY-MM-DD for birth_date and date. The API will return 422 for invalid formats.
5. Multilingual support: Pass language to get readings in the user’s preferred language. AI generates native-quality text, not translations.
6. Handle master numbers: Display master numbers (11, 22, 33) prominently — they carry special significance. The API flags them in responses.
7. Handle rate limits: Implement exponential backoff for 429 responses.

#API Changelog