Use case
A numerology API for apps
Updated
How it works
- 1Your app sends the user's name, in English letters, and date of birth.
- 2The API adds up the numbers and returns each one with a short reading.
- 3Your app shows them on its own screens, in English or Hindi.
POST /v1/cycles?as_of=2026-10-01200 OK{
"as_of": "2026-10-01",
"year": {
"number": 6,
"reading": "A year for home, family and duties. People may lean on you."
},
"month": {
"number": 7
},
"day": {
"number": 8
}
}What you send, what you get, what it costs
| You send | A name in English letters and a date of birth. No birth time or place. |
|---|---|
| You get | The mulank, bhagyank and name number, a daily number, the personal year, the life path and a printable report, each with a short reading in 2 languages. |
| It costs | 3 credits for a user's core numbers, 1 credit for a daily number and 25 credits for a report. |
| Credits in a plan | The Free plan has 150 reading credits a month. Paid plans have more: Starter 1,000, Growth 5,000, Scale 22,000. Failed calls are free. |
How to build a numerology app on the API
- 01
Show the core numbers at sign-up
POST /v1/profile3 creditsThe mulank, the bhagyank and the name number, each with a short reading. It also returns the lucky day and the Lo Shu grid. The grid is a 3 by 3 square filled from the birth date.
- 02
Add the life path for Western users
POST /v1/western3 creditsThe life path, expression, soul urge and personality numbers, in the Pythagorean system. The life path is the main number in Western numerology. John Doe's is 6. It needs the full name from birth and the birth date.
- 03
A daily number
GET /v1/day1 creditThe date's own number and its theme, the same for everyone. It also says how each of the nine mulanks gets along with that number. Show the user the line for their mulank.
- 04
Personal year, month and day
POST /v1/cycles2 creditsThe user's own personal year, month and day for a date, each with a short reading. The year comes with things to do and things to avoid. Only the birth date is needed.
- 05
Sell a full report
POST /v1/report25 creditsThe whole reading as one printable HTML page, or the same chapters as JSON for your own layout.
Credits per flow: 34 credits for one of each call above, on a live key.
Step 1 in code: show the core numbers at sign-up
Send the details as JSON with your API key in the Authorization header. The other steps work the same way. Each one links to its page in the API reference.
POST /v1/profile
# John Doe, born Aug 15, 1990
curl -X POST "https://apiforastrology.com/api/numerology/v1/profile" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"John Doe","birth_date":"1990-08-15"}'{
"input": {
"name": "John Doe",
"birth_date": "1990-08-15"
},
"mulank": {
"number": 6,
"planet": "Venus",
"planet_name": "Venus",
"about": "Your mulank (birth day number) comes from the day you were born. It shows how you act day to day and how people first see you.",
"reading": "You care about home, family and things that look good. People feel welcome around you. Watch for spending too much on comfort.",
"topics": [
{
"facet": "nature",
"title": "Nature",
"text": "Mulank 6 is ruled by Venus. You care about home, family and things that look good. People feel welcome around you, and you often keep peace in a group. You…"
},
{
"facet": "career",
"title": "Career",
"text": "You tend to work best in a pleasant place where you can make things better for people. You often have taste and a gift for making people feel at ease. Harsh or…"
}
]
},
"bhagyank": {
"number": 6,
"total": 33,
"master": true,
"planet": "Venus",
"planet_name": "Venus",
"about": "Your bhagyank (destiny number) comes from your full birth date. It shows the direction your life tends to take as you grow older.",
"reading": "Your life tends to center on family, love and responsibility. Work linked to beauty, art, care or comfort often suits this path.",
"topics": [
{
"facet": "nature",
"title": "Nature",
"text": "With Venus behind your bhagyank, care for family and a love of beauty tend to grow with age. You often become the one who brings people together and makes a…"
},
{
"facet": "career",
"title": "Career",
"text": "Your path tends to grow around beauty, care and comfort. You often do well in work that makes people's lives nicer or easier. Fields that tend to suit you…"
}
]
},
"name_number": {
"default_system": "chaldean",
"chaldean": {
"system": "chaldean",
"name": "John Doe",
"total": 34,
"compound": 34,
"number": 7,
"master": false,
"words": [
{
"word": "John",
"total": 18,
"number": 9
},
{
"word": "Doe",
"total": 16,
"number": 7
}
],
"system_name": "Chaldean",
"planet": "Ketu",
"planet_name": "Ketu",
"about": "Your name number comes from the letters of your name. It shows how your name shapes the way people take you.",
"reading": "Your name gives a quiet, thoughtful feel. People may see you as private or deep."
},
"pythagorean": {
"system": "pythagorean",
"name": "John Doe",
"total": 35,
"compound": 35,
"number": 8,
"master": false,
"words": [
{
"word": "John",
"total": 20,
"number": 2
},
{
"word": "Doe",
"total": 15,
"number": 6
}
],
"system_name": "Pythagorean",
"read": false
}
},
"lucky": {
"from": "mulank",
"planet": "Venus",
"planet_name": "Venus",
"day": "Friday",
"day_name": "Friday",
"day_via": null,
"colors": [
{
"color": "white",
"name": "white"
},
{
"color": "pastel pink",
"name": "pastel pink"
}
],
"numbers": {
"friendly": [
4,
5
],
"neutral": [
3,
7
],
"unfriendly": [
1,
2
]
},
"dates": [
4,
5
],
"dates_about": "Dates of the month that add up to a number friendly to your mulank. They tend to suit starting things."
},
"remedies": {
"from": "mulank",
"planet": "Venus",
"planet_name": "Venus",
"direction": "south-east",
"direction_name": "South-east",
"direction_about": "The direction linked to your ruling planet. Facing it for work or study is a common practice.",
"deity": "Lakshmi",
"deity_name": "Lakshmi",
"deity_about": "The deity often worshipped for your ruling planet. Families and regions may follow other customs.",
"fast_day": "Friday",
"fast_day_name": "Friday",
"fast_about": "The weekday of your ruling planet. People who fast for this planet usually keep this day.",
"gemstone": {
"stone": "diamond",
"metal": "silver or platinum",
"finger": "middle",
"caution": null,
"stone_name": "Diamond (heera)",
"metal_name": "silver or platinum",
"finger_name": "middle finger",
"about": "The stone linked to your ruling planet. Numbers alone cannot say whether you should wear it, so check your birth chart with an astrologer first."
},
"mantra": {
"key": "venus:beeja",
"text": "ॐ द्रां द्रीं द्रौं सः शुक्राय नमः",
"latin": "Om Draam Dreem Draum Sah Shukraya Namah",
"audio": "shukra-beej-mantra.mp3",
"daily": 108,
"japa": 16000,
"japa_sources": [],
"about": "The beej mantra (short seed mantra) of your ruling planet. One round is 108 times. The full count is for a complete practice.",
"japa_note": null
}
},
"loshu": {
"cells": [
[
{
"number": 4,
"count": 0
},
{
"number": 9,
"count": 2
}
],
[
{
"number": 3,
"count": 0
},
{
"number": 5,
"count": 1
}
]
],
"placed": [
{
"number": 1,
"from": "date",
"from_name": "birth date"
},
{
"number": 5,
"from": "date",
"from_name": "birth date"
}
],
"missing": [
{
"number": 2,
"reading": "2 is missing. You may not always notice how others feel. Slowing down to listen helps."
},
{
"number": 3,
"reading": "3 is missing. Planning ahead may not come easily. Writing your plans down can help."
}
],
"repeated": [
{
"number": 1,
"count": 2,
"reading": "1 appears more than once. Your self-belief is strong. Too much of it can come across as pride."
},
{
"number": 6,
"count": 2,
"reading": "6 appears more than once. You care a lot for home and family. Do not carry everyone's load alone."
}
],
"planes": [
{
"id": "practical",
"numbers": [
8,
1
],
"state": "full",
"name": "Practical line",
"reading": "The practical line is full. You tend to be good with hands-on work and money matters."
},
{
"id": "will",
"numbers": [
9,
5
],
"state": "full",
"name": "Willpower line",
"reading": "The willpower line is full. Once you decide, you tend to see it through."
}
],
"basis": "Non-zero digits of the birth date (DD MM YYYY), plus the bhagyank, plus the mulank when the day has two digits. Zero has no cell.",
"about": "The Lo Shu grid is a 3 by 3 square of the numbers 1 to 9. The digits of your birth date are placed in it. Numbers that are missing or repeated show what comes…",
"summary": {
"strong": [
{
"from": "number",
"number": 1,
"area": "self-belief"
},
{
"from": "number",
"number": 6,
"area": "caring for family"
}
],
"effort": [
{
"from": "number",
"number": 2,
"area": "noticing how others feel"
},
{
"from": "number",
"number": 3,
"area": "planning ahead"
}
],
"text": "Comes easily to you: self-belief, caring for family, drive, hands-on work and money and seeing things through. Needs more effort: noticing how others feel,…"
},
"number_tip": {
"digits": [
2,
3
],
"text": "Many people choose a mobile or vehicle number that has their missing numbers (2, 3, 4 and 7). This is a popular belief, not a promise."
},
"birth_only": "Your grid comes only from your birth date. Changing your name does not change it."
},
"not_included": {
"compound_meanings": "The compound number (10 to 52) is returned, but not read: its meanings wait for the astrologer.",
"western_numbers": "Life path, expression, soul urge, pinnacles, life cycles and the personal year come from the western route."
},
"not_claimed": "Numbers describe tendencies, not fixed events. Use them as a guide, not a rule.",
"localization": {
"lang": "en",
"detail": "standard",
"fell_back_to_en": [],
"fell_back_to_standard": []
}
}Tips for going live
- Make every call from your backend. A key shipped inside a mobile app can be pulled out of it.
- Ask for the name in English letters, as the user writes it. The Western numbers need the full name from birth. Another script is refused.
- Send the user's own date as date or as_of. Left out, the API uses its own today, which can differ from the user's local date.
- Use detail=standard for app cards and detail=expanded for a screen read in full. The price is the same.
- Every reading has a not_claimed line saying that numbers describe tendencies, not fixed events. Show it near the readings.
Where the rules come from
The mulank (birth day number) is the day of birth, added down to one digit. The 1st, 10th, 19th and 28th all give 1, as in Cheiro's Book of Numbers (1926). The life path reduces the month, the day and the year one by one, then adds them. The same steps appear in L. Dow Balliett's The Philosophy of Numbers (1908). The Lo Shu square holds the numbers 1 to 9 once each. Every line adds to 15, as shown by Wolfram MathWorld.
What it costs
A daily number costs 1 credit a user a day, so 1,000 daily users use about 30,000 credits a month.
Numerology uses reading credits from your plan, never calls, and the same key as the Astrology API. Test keys are free, with 1,000 test calls a month, and answer for the sample people. Failed requests are free.
Numerology API pricingFeatures used here
- Core numbersMulank, bhagyank, name number and Lo Shu grid
- Number checksMobile, vehicle, house and business numbers
- CompatibilityTwo people's numbers, read both ways
- Western numbersLife path, expression and soul urge
- Personal year and datesPersonal year, month and day, and good dates
- Baby namesNames whose number suits the child
- Numerology reportThe full report, HTML or JSON
Read next
- The Western numbersEverything POST /v1/western returns, from the life path to the pinnacles.
- What a personal year isThe year's theme for one person, and how the API works it out.
- A sample numerology reportThe full report your app can sell, made for John Doe.
- Make your first callA key, one request and the answer, step by step.
Other numerology use cases:
From the blog

· 17 min read
Numerology Chatbots: Give an AI Assistant Real Numbers
Build a numerology chatbot that never invents a number.
Read
· 9 min read
Indian vs Western Numerology: What Your App Should Show
Indian numerology gives a mulank, bhagyank and planets.
Read
· 9 min read
Numerology App Development: What to Build and What to Buy
Planning a numerology app?
Read
Common questions
All questionsWhat does a user need to enter?
A full name in English letters and a date of birth. No birth time or place is needed. The personal year needs only the birth date, and the daily number needs no birth details at all.
Read the conventionsWhat is the difference between the daily number and the personal day?
GET /v1/day gives the date's own number, the same for everyone. It also says how each of the nine mulanks gets along with it. POST /v1/cycles gives the personal day, worked out from the user's birth date, with the personal year and month. The first costs 1 credit and the second 2.
What a personal day isCan the app show Western numbers such as the life path?
Yes. POST /v1/western returns the life path, expression, soul urge and personality numbers, and more, in the Pythagorean system. The master numbers 11, 22 and 33 are kept in number, with the single digit beside them in digit. It costs 3 credits.
About the Western numbersCan we sell a report inside the app?
Yes. POST /v1/report returns the whole reading as one printable HTML page, or the same chapters as JSON. Send brand to print your app's name at the top of the cover. Each report costs 25 credits.
About the numerology reportCan the app show readings in Hindi?
Yes. Send lang=hi for Hindi. Codes such as planet and outcome stay in English. The words in the reader's language sit beside them in *_name fields. The price is the same in every language.
Read the conventionsWhy was a user's name refused?
Names must be in English letters (A to Z). Spaces, dots, hyphens and apostrophes are allowed. A name in another script gets a 422 error, and error.field names the field. The API does not guess an English spelling, because each spelling gives a different number.
How names are readCan we build the app on a test key?
Yes, with the sample people. Test keys answer for John Doe, born August 15, 1990, and Jane Doe, born March 22, 1992. They work for today or the dates in the docs. Each test call counts as 1 test call and uses no credits. Use a live key for real users.
Make your first callNumerology API
Start with a free test key
Create an account and a test key, then try each step above with the sample people. Need more than the largest plan? Write to us.
Your first answer
John Doe, born Aug 15, 1990
- Mulank6Venus
- Bhagyank6Destiny number
- Name number7Ketu
Real API output. A free test key gets the same answer.
01
Test key: 1,000 test calls a month to build with
02
Free plan: 2,000 live calls a month, no card needed
03
One key: the same key, plan and reading credits as the Astrology API