Personal year number API reference
Updated
The date endpoints of API for Astrology (apiforastrology.com) work out personal cycles and good dates with numerology. POST /v1/cycles returns a person's personal year, month and day from the birth date alone. Other endpoints list the good dates in a month, read a year for one mulank, or read any date. The group has 4 endpoints.
Call POST /v1/cycles with a birth date. John Doe's personal year in 2026 is 6. It needs no name, so it suits a daily screen. Leave out as_of for today. POST /v1/dates lists one person's good dates in a month. GET /v1/year/{mulank} and GET /v1/day need no birth date at all. How the personal year number is worked out shows the math.
Dates and cycles: the personal year, month and day, the good dates in a month, a calendar year for a mulank, and the number of any day.
4 endpoints. Paths are relative to https://apiforastrology.com/api/numerology. Send your API key in the Authorization: Bearer header (see authentication). No key yet? Get a key. To send test requests from the browser, open the interactive reference.
Overview: Personal year and dates.
Which date endpoint to call
| What you need | Endpoint | Cost |
|---|---|---|
| A person's personal year, month and day. Start here | POST /v1/cycles | 2 reading credits |
| A calendar year read for one mulank, with no birth date | GET /v1/year/{mulank} | 2 reading credits |
| A date's number and theme, the same for everyone | GET /v1/day | 1 reading credit |
| The good dates in a month for one person | POST /v1/dates | 1 reading credit |
Personal year, month and day
POST /v1/cycles
The personal year, month and day for one date, each with a short reading. Needs only the birth date, so it suits a daily screen. The personal year changes on January 1.
Uses 2 reading credits. On live keys a successful response uses them from your monthly reading credits, and no calls. Test keys answer for the sample people only, and it counts as 1 test call. What reading credits buy.
Cost: 2 reading credits on a live key, 1 test call on a test key.
Required inputs
| Name | In | What it is |
|---|---|---|
| birth_date | body | Date of birth, YYYY-MM-DD. |
Optional inputs (3), with their defaults
| Name | In | What it does |
|---|---|---|
| as_of | query | The date to read the personal year, month and day (and the current pinnacle and life cycle) for, YYYY-MM-DD. Defaults to today. Echoed back in as_of. |
| lang | query | Language of the readings and names: en, hi. Codes stay in English. |
| detail | query | Length of the readings: standard (the default, short, for app cards) or expanded (about three times longer, for reading in full). A passage with no long form yet comes back at standard length and is listed in localization.fell_back_to_standard. |
Main response fields
birth_date(string)as_of(string)year(object): holds number, about, reading, do, avoid.month(object): holds number, about, reading.day(object): holds number, about, reading.not_claimed(string)localization(object): holds lang, detail, fell_back_to_en, fell_back_to_standard.
# John Doe, born Aug 15, 1990
curl -X POST "https://apiforastrology.com/api/numerology/v1/cycles?as_of=2026-10-01" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"birth_date":"1990-08-15"}'{
"birth_date": "1990-08-15",
"as_of": "2026-10-01",
"year": {
"number": 6,
"about": "Your personal year number shows the theme of this year for you. It changes on January 1.",
"reading": "A year for home, family and duties. People may lean on you.",
"do": "Give time to your home and family. Help the people who lean on you, and plan what you can do for them. Fix or improve something at home. Spend time with your…",
"avoid": "Avoid taking on every duty yourself. Try not to give advice or help where it is not wanted. Do not forget your own rest while you care for others. Avoid…"
},
"month": {
"number": 7,
"about": "Your personal month number shows the theme of this month for you.",
"reading": "This month tends to favor rest, study and thinking things over. You may want more quiet time than usual. It is a good time to read, plan and look inward,…"
},
"day": {
"number": 8,
"about": "Your personal day number shows the theme of this day for you.",
"reading": "Good for work, money and big decisions."
},
"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": []
}
}Example from a real call for John Doe, born Aug 15, 1990. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Personal year and dates.
A year for a mulank
GET /v1/year/{mulank}
A calendar year read for one mulank, with no birth date. The year adds up to one number, the same for everyone (2027 adds up to 11, then 2). year_number says how the mulank gets along with it. It uses the same one-sided planet friendship as the rest of the API, so outcome is good, neutral or difficult. months reads each month the same way (the year's number plus the month).
Uses 2 reading credits. On live keys a successful response uses them from your monthly reading credits, and no calls. Test keys answer for the sample people only, and it counts as 1 test call. What reading credits buy.
Cost: 2 reading credits on a live key, 1 test call on a test key.
Required inputs
| Name | In | What it is |
|---|---|---|
| mulank | path | The mulank, from 1 to 9. |
Optional inputs (3), with their defaults
| Name | In | What it does |
|---|---|---|
| year | query | The calendar year. Defaults to this year. |
| lang | query | Language of the readings and names: en, hi. Codes stay in English. |
| detail | query | Length of the readings: standard (the default, short, for app cards) or expanded (about three times longer, for reading in full). A passage with no long form yet comes back at standard length and is listed in localization.fell_back_to_standard. |
Main response fields
mulank(number)mulank_planet(string)mulank_planet_name(string)year(number)about(string)year_number(object): holds number, planet, planet_name, relation, via, outcome, relation_name, outcome_name, reading, theme.months(array of objects): each item holds month, month_name, number, planet, planet_name, outcome, outcome_name, theme.not_claimed(string)localization(object): holds lang, detail, fell_back_to_en, fell_back_to_standard.
# Mulank 4 in 2026
curl "https://apiforastrology.com/api/numerology/v1/year/4?year=2026" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY"{
"mulank": 4,
"mulank_planet": "Rahu",
"mulank_planet_name": "Rahu",
"year": 2026,
"about": "Every calendar year adds up to one number, the same for everyone. For example, 2027 adds up to 11, then to 2. How your mulank gets along with that number…",
"year_number": {
"number": 1,
"planet": "Sun",
"planet_name": "Sun",
"relation": "enemy",
"via": [
"Rahu"
],
"outcome": "difficult",
"relation_name": "unfriendly",
"outcome_name": "Not a good fit",
"reading": "Your mulank does not get along easily with this year's number. Things may take more effort or patience. Plan carefully and do not rush big decisions.",
"theme": "A year that adds up to 1 tends to favor new starts, bold moves and standing on your own."
},
"months": [
{
"month": 1,
"month_name": "January",
"number": 2,
"planet": "Moon",
"planet_name": "Moon",
"outcome": "difficult",
"outcome_name": "Not a good fit",
"theme": "Good for teamwork and quiet patience."
},
{
"month": 2,
"month_name": "February",
"number": 3,
"planet": "Jupiter",
"planet_name": "Jupiter",
"outcome": "neutral",
"outcome_name": "Neutral",
"theme": "Good for meeting people and sharing ideas."
}
],
"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": []
}
}Example from a real call for Mulank 4 in 2026. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Personal year and dates.
A day's number
GET /v1/day
A date's number (every digit added, the same for everyone) and its theme. It also shows how each of the nine mulanks gets along with it. mulanks[] gives each one's outcome (good, neutral or difficult) and a one-line reading. No birth date needed. For a personal day, use the cycles route.
Uses 1 reading credit. On live keys a successful response uses them from your monthly reading credits, and no calls. Test keys answer for the sample people only, and it counts as 1 test call. What reading credits buy.
Cost: 1 reading credit on a live key, 1 test call on a test key.
Required inputs
None.
Optional inputs (3), with their defaults
| Name | In | What it does |
|---|---|---|
| date | query | The date, YYYY-MM-DD. Defaults to today. |
| lang | query | Language of the readings and names: en, hi. Codes stay in English. |
| detail | query | Length of the readings: standard (the default, short, for app cards) or expanded (about three times longer, for reading in full). A passage with no long form yet comes back at standard length and is listed in localization.fell_back_to_standard. |
Main response fields
date(string)number(number)planet(string)planet_name(string)about(string)theme(string)mulanks(array of objects): each item holds mulank, mulank_planet, mulank_planet_name, relation, via, outcome, relation_name, outcome_name, reading.not_claimed(string)localization(object): holds lang, detail, fell_back_to_en, fell_back_to_standard.
# Oct 1, 2026
curl "https://apiforastrology.com/api/numerology/v1/day?date=2026-10-01" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY"{
"date": "2026-10-01",
"number": 3,
"planet": "Jupiter",
"planet_name": "Jupiter",
"about": "Every date adds up to one number, the same for everyone. How your mulank gets along with today's number shows whether the day tends to suit you.",
"theme": "Good for meeting people and sharing ideas.",
"mulanks": [
{
"mulank": 1,
"mulank_planet": "Sun",
"mulank_planet_name": "Sun",
"relation": "friend",
"via": [],
"outcome": "good",
"relation_name": "friendly",
"outcome_name": "Good fit",
"reading": "A good day for you. Use it for things that matter."
},
{
"mulank": 2,
"mulank_planet": "Moon",
"mulank_planet_name": "Moon",
"relation": "neutral",
"via": [],
"outcome": "neutral",
"relation_name": "neutral",
"outcome_name": "Neutral",
"reading": "An ordinary day for you. Keep to your plans."
}
],
"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": []
}
}Example from a real call for Oct 1, 2026. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Personal year and dates.
Good dates in a month
POST /v1/dates
Every date of a month read for one person. The date's own number (every digit added) is read against their mulank and bhagyank. It uses the same rule as a phone number, so outcome is good, neutral, mixed or difficult. good lists the good dates. Each day also carries personal_day (1-9) as a theme; it is not judged.
Uses 1 reading credit. On live keys a successful response uses them from your monthly reading credits, and no calls. Test keys answer for the sample people only, and it counts as 1 test call. What reading credits buy.
Cost: 1 reading credit on a live key, 1 test call on a test key.
Required inputs
| Name | In | What it is |
|---|---|---|
| birth_date | body | Date of birth, YYYY-MM-DD. |
Optional inputs (3), with their defaults
| Name | In | What it does |
|---|---|---|
| month | query | The month, YYYY-MM. Defaults to this month. |
| lang | query | Language of the readings and names: en, hi. Codes stay in English. |
| detail | query | Length of the readings: standard (the default, short, for app cards) or expanded (about three times longer, for reading in full). A passage with no long form yet comes back at standard length and is listed in localization.fell_back_to_standard. |
Main response fields
person(object): holds birth_date, mulank, bhagyank.year(number)month(number)month_name(string)about(string)rule(string)days(array of objects): each item holds date, day, weekday, number, planet, planet_name, outcome, outcome_name, personal_day.good(array of numbers)none(null)not_claimed(string)localization(object): holds lang, detail, fell_back_to_en, fell_back_to_standard.
# John Doe, born Aug 15, 1990, October 2026
curl -X POST "https://apiforastrology.com/api/numerology/v1/dates?month=2026-10" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"birth_date":"1990-08-15"}'{
"person": {
"birth_date": "1990-08-15",
"mulank": 6,
"bhagyank": 6
},
"year": 2026,
"month": 10,
"month_name": "October",
"about": "Each date adds up to its own number. Here every date of the month is read against your mulank and bhagyank, the same way a phone number is.",
"rule": "A good date is one whose number gets along well with your own numbers and does not clash with either.",
"days": [
{
"date": "2026-10-01",
"day": 1,
"weekday": 4,
"number": 3,
"planet": "Jupiter",
"planet_name": "Jupiter",
"outcome": "neutral",
"outcome_name": "Neutral",
"personal_day": 8
},
{
"date": "2026-10-02",
"day": 2,
"weekday": 5,
"number": 4,
"planet": "Rahu",
"planet_name": "Rahu",
"outcome": "good",
"outcome_name": "Good fit",
"personal_day": 9
}
],
"good": [
2,
3
],
"none": null,
"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": []
}
}Example from a real call for John Doe, born Aug 15, 1990, October 2026. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Personal year and dates.
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).
Related pages
- Features: Personal year and dates.
- Used for: Numerology apps, Business naming tools, Matrimony and matchmaking sites.
- Guides: Quickstart, Conventions, Errors, Changelog.