Name numerology API reference
Updated
The name numerology endpoints of API for Astrology (apiforastrology.com) check how well a name suits a person. You send a name, up to 10 other spellings and a birth date. Each spelling gets a fit: good, neutral, mixed or difficult. Other endpoints suggest spellings and find baby names. The group has 3 endpoints.
Call POST /v1/name with the name, its other spellings and the birth date. John Doe's name adds up to 7 in Chaldean numerology, the system the API reads. The Chaldean vs Pythagorean guide shows why another app may say 8. POST /v1/name/suggest finds spellings that sound the same and suit the person. POST /v1/baby-names finds names for a child. Write names in English letters: a name in another script gets a 422 error.
Names: a name and its spellings against a person's numbers, spellings that sound the same and suit them, and baby names whose number suits a child.
3 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: Name checker, Baby names.
Which name endpoint to call
| What you need | Endpoint | Cost |
|---|---|---|
| A check of a name and up to 10 spellings. Start here | POST /v1/name | 1 reading credit |
| Spellings that sound the same and suit the person | POST /v1/name/suggest | 1 reading credit |
| Baby names whose number suits the child | POST /v1/baby-names | 2 reading credits |
Name checker
POST /v1/name
Reads a name, and up to 10 other spellings of it, against the person's mulank and bhagyank. Each spelling gets its Chaldean and Pythagorean numbers and a fit: good, neutral, mixed or difficult, with the one-sided relation behind it. The rule: a friend and no enemy is good; an enemy and no friend is difficult; one of each is mixed; neither is neutral. Spellings come back in the order sent and are never ranked.
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 |
|---|---|---|
| name | body | Full name as it is written and used, in English letters (A to Z). Spaces, dots, hyphens and apostrophes are allowed. Other scripts are refused, because the spelling changes the number. |
| birth_date | body | Date of birth, YYYY-MM-DD. The calendar date is used as it is, with no time of day. |
Optional inputs (3), with their defaults
| Name | In | What it does |
|---|---|---|
| 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. |
| variants | body | Other spellings to compare, up to 10. Returned in the order given, never ranked. |
Main response fields
person(object): holds birth_date, mulank, bhagyank.system(string)about(string)spellings(array of objects): each item holds name, chaldean, pythagorean, planet, planet_name, fit.ranked(boolean)not_claimed(string)localization(object): holds lang, detail, fell_back_to_en, fell_back_to_standard.
# John Doe, born Aug 15, 1990, with two other spellings
curl -X POST "https://apiforastrology.com/api/numerology/v1/name" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"John Doe","birth_date":"1990-08-15","variants":["Jon Doe","John Dow"]}'{
"person": {
"birth_date": "1990-08-15",
"mulank": 6,
"bhagyank": 6
},
"system": "chaldean",
"about": "A name is read from its letters.",
"spellings": [
{
"name": "John Doe",
"chaldean": {
"total": 34,
"compound": 34,
"number": 7,
"master": false,
"words": [
{
"word": "John",
"total": 18,
"number": 9
},
{
"word": "Doe",
"total": 16,
"number": 7
}
]
},
"pythagorean": {
"total": 35,
"number": 8,
"master": false
},
"planet": "Ketu",
"planet_name": "Ketu",
"fit": {
"number": 7,
"links": [
{
"from": "mulank",
"from_number": 6,
"to_number": 7,
"relation": "neutral",
"via": [
"Ketu"
],
"from_name": "mulank",
"relation_name": "neutral"
},
{
"from": "bhagyank",
"from_number": 6,
"to_number": 7,
"relation": "neutral",
"via": [
"Ketu"
],
"from_name": "bhagyank",
"relation_name": "neutral"
}
],
"outcome": "neutral",
"outcome_name": "Neutral",
"reading": "This number is neutral to your own numbers. It neither helps nor gets in the way much."
}
},
{
"name": "Jon Doe",
"chaldean": {
"total": 29,
"compound": 29,
"number": 2,
"master": true,
"words": [
{
"word": "Jon",
"total": 13,
"number": 4
},
{
"word": "Doe",
"total": 16,
"number": 7
}
]
},
"pythagorean": {
"total": 27,
"number": 9,
"master": false
},
"planet": "Moon",
"planet_name": "Moon",
"fit": {
"number": 2,
"links": [
{
"from": "mulank",
"from_number": 6,
"to_number": 2,
"relation": "enemy",
"via": [],
"from_name": "mulank",
"relation_name": "unfriendly"
},
{
"from": "bhagyank",
"from_number": 6,
"to_number": 2,
"relation": "enemy",
"via": [],
"from_name": "bhagyank",
"relation_name": "unfriendly"
}
],
"outcome": "difficult",
"outcome_name": "Not a good fit",
"reading": "This number does not get along with your own numbers. It may get in your way more than it helps."
}
}
],
"ranked": false,
"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, with two other spellings. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Name checker. Free tool: Name numerology calculator.
Name spelling suggestions
POST /v1/name/suggest
Spellings of one word of the name (part, default the first name) that sound the same. Each gives a Chaldean name number in targets (default: every number whose fit with the person is good). Only common spelling habits are tried, at most two at a time. They are a/aa, i/ee, u/oo, v/w (not as the first letter) and ph/f, plus a doubled last consonant and a silent h after a final a. Each suggestion lists its changes. Suggestions come in a fixed order (fewer changes first, then A to Z) and are never ranked. found counts every match before limit; none is a sentence when there is no match.
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 |
|---|---|---|
| name | body | Full name as it is written and used, in English letters (A to Z). Spaces, dots, hyphens and apostrophes are allowed. Other scripts are refused, because the spelling changes the number. |
| birth_date | body | Date of birth, YYYY-MM-DD. The calendar date is used as it is, with no time of day. |
Optional inputs (5), with their defaults
| Name | In | What it does |
|---|---|---|
| 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. |
| part | body | Which word of the name to change, from 0 (the first). Default 0, the first name. |
| targets | body | Name numbers (1 to 9) to aim for. Leave out to use every number whose fit with the person is good. |
| limit | body | Most suggestions to return (1 to 50). |
Main response fields
name(string)part(number)word(string)current(object): holds total, compound, number, planet, planet_name, fit.targets(array of numbers)tried(number)found(number)suggestions(array)person(object): holds birth_date, mulank, bhagyank.system(string)about(string)none(string)ranked(boolean)not_claimed_spelling(string)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/name/suggest" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"John Doe","birth_date":"1990-08-15"}'{
"name": "John Doe",
"part": 0,
"word": "John",
"current": {
"total": 34,
"compound": 34,
"number": 7,
"planet": "Ketu",
"planet_name": "Ketu",
"fit": {
"number": 7,
"links": [
{
"from": "mulank",
"from_number": 6,
"to_number": 7,
"relation": "neutral",
"via": [
"Ketu"
],
"from_name": "mulank",
"relation_name": "neutral"
},
{
"from": "bhagyank",
"from_number": 6,
"to_number": 7,
"relation": "neutral",
"via": [
"Ketu"
],
"from_name": "bhagyank",
"relation_name": "neutral"
}
],
"outcome": "neutral",
"outcome_name": "Neutral",
"reading": "This number is neutral to your own numbers. It neither helps nor gets in the way much."
}
},
"targets": [
4,
5
],
"tried": 1,
"found": 0,
"suggestions": [],
"person": {
"birth_date": "1990-08-15",
"mulank": 6,
"bhagyank": 6
},
"system": "chaldean",
"about": "These spellings sound the same as your name but add up to a number that suits you. Only small, common spelling changes are tried.",
"none": "No small spelling change gives a number that suits you. Your current spelling can stay as it is.",
"ranked": false,
"not_claimed_spelling": "A new spelling changes the number of the name, not the person. Choose one only if you are happy to use it every day.",
"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: Name checker.
Baby name finder
POST /v1/baby-names
Names from our own list whose Chaldean number suits the child, read by the same rule as the name checker. With a surname the full name is counted. Filter by gender, origin, first syllables in Devanagari or Gujarati letters (for naming by birth star) or English starting letters. Results are groups, one per number, A to Z inside, never ranked; each group gives found so limit never hides how many exist. per_syllable and syllables_without_names show which starting sounds have no name yet. Names with a sensitive meaning are never suggested (list.kept_out). A modern name with no known meaning is suggested, with meaning_known: false. Each name gives origin as the list has it (use it to filter) and origin_name in the reader's language. The list is not yet reviewed (list.reviewed, review_note).
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 | The child's date of birth, YYYY-MM-DD. |
Optional inputs (9), with their defaults
| Name | In | What it does |
|---|---|---|
| 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. |
| surname | body | Family name in English letters. When given, each name is read with it, as the child will carry it. |
| gender | body | boy or girl also include names used for both. |
| origin | body | indian (default) or all names in the list. |
| syllables | body | First syllables for naming by birth star, in Devanagari (Hindi or Marathi) letters such as चू or ला, or in Gujarati letters such as ચૂ, which are read as the same sounds. The astrology API gives the four for a birth star. |
| letters | body | English starting letters, 1 to 3 each, such as A or Sh. |
| targets | body | Name numbers (1 to 9) to look for. Leave out to use every number whose fit with the child is good. |
| limit | body | Most names to return for each number (1 to 200). |
Main response fields
person(object): holds birth_date, mulank, bhagyank.system(string)filters(object): holds surname, gender, origin, syllables, letters.about(string)targets(array of numbers)searched(number)found(number)groups(array of objects): each item holds number, planet, planet_name, fit, found, names.per_syllable(null)syllables_without_names(array)syllable_note(null)none(null)ranked(boolean)list(object): holds reviewed, in_list, suggestable, kept_out, meaning_unknown.review_note(string)not_claimed_name(string)not_claimed(string)localization(object): holds lang, detail, fell_back_to_en, fell_back_to_standard.
# A boy born Mar 22, 1992, surname Doe, names starting with J
curl -X POST "https://apiforastrology.com/api/numerology/v1/baby-names" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"birth_date":"1992-03-22","surname":"Doe","gender":"boy","letters":["J"]}'{
"person": {
"birth_date": "1992-03-22",
"mulank": 4,
"bhagyank": 1
},
"system": "chaldean",
"filters": {
"surname": "Doe",
"gender": "boy",
"origin": "indian",
"syllables": null,
"letters": [
"J"
]
},
"about": "These names add up to a number that suits your child. The number is worked out from the date of birth. With a surname, the full name is counted.",
"targets": [
3,
5
],
"searched": 95,
"found": 28,
"groups": [
{
"number": 3,
"planet": "Jupiter",
"planet_name": "Jupiter",
"fit": {
"number": 3,
"links": [
{
"from": "mulank",
"from_number": 4,
"to_number": 3,
"relation": "neutral",
"via": [
"Rahu"
],
"from_name": "mulank",
"relation_name": "neutral"
},
{
"from": "bhagyank",
"from_number": 1,
"to_number": 3,
"relation": "friend",
"via": [],
"from_name": "bhagyank",
"relation_name": "friendly"
}
],
"outcome": "good",
"outcome_name": "Good fit",
"reading": "This number gets along well with your own numbers. It tends to support you."
},
"found": 14,
"names": [
{
"name": "Jahaan",
"full_name": "Jahaan Doe",
"devanagari": "जहान",
"meaning": "The world",
"meaning_known": true,
"gender": "boy",
"gender_name": "Boy",
"origin": "Persian",
"origin_name": "Persian",
"first_syllable": "ज",
"variants": [],
"number": 3,
"first_name_number": 5,
"needs_check": false
},
{
"name": "Jaimini",
"full_name": "Jaimini Doe",
"devanagari": "जैमिनी",
"meaning": "A great sage",
"meaning_known": true,
"gender": "boy",
"gender_name": "Boy",
"origin": "Hindu",
"origin_name": "Hindu",
"first_syllable": "जै",
"variants": [],
"number": 3,
"first_name_number": 5,
"needs_check": false
}
]
},
{
"number": 5,
"planet": "Mercury",
"planet_name": "Mercury",
"fit": {
"number": 5,
"links": [
{
"from": "mulank",
"from_number": 4,
"to_number": 5,
"relation": "friend",
"via": [
"Rahu"
],
"from_name": "mulank",
"relation_name": "friendly"
},
{
"from": "bhagyank",
"from_number": 1,
"to_number": 5,
"relation": "neutral",
"via": [],
"from_name": "bhagyank",
"relation_name": "neutral"
}
],
"outcome": "good",
"outcome_name": "Good fit",
"reading": "This number gets along well with your own numbers. It tends to support you."
},
"found": 14,
"names": [
{
"name": "Jaideep",
"full_name": "Jaideep Doe",
"devanagari": "जयदीप",
"meaning": "Lamp of victory",
"meaning_known": true,
"gender": "boy",
"gender_name": "Boy",
"origin": "Sanskrit",
"origin_name": "Sanskrit",
"first_syllable": "ज",
"variants": [],
"number": 5,
"first_name_number": 7,
"needs_check": false
},
{
"name": "Jainendra",
"full_name": "Jainendra Doe",
"devanagari": "जैनेंद्र",
"meaning": "Lord of the Jains",
"meaning_known": true,
"gender": "boy",
"gender_name": "Boy",
"origin": "Hindu",
"origin_name": "Hindu",
"first_syllable": "जै",
"variants": [],
"number": 5,
"first_name_number": 7,
"needs_check": false
}
]
}
],
"per_syllable": null,
"syllables_without_names": [],
"syllable_note": null,
"none": null,
"ranked": false,
"list": {
"reviewed": false,
"in_list": 13859,
"suggestable": 13682,
"kept_out": {
"sensitive": 177,
"unreadable": 0
},
"meaning_unknown": 1373
},
"review_note": "Our name list is still being checked. A meaning or Hindi spelling may change.",
"not_claimed_name": "A number is one thing to think about, not the only one. Choose a name your family loves and will use every day.",
"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 A boy born Mar 22, 1992, surname Doe, names starting with J. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Baby names.
Where the rules come from
The Chaldean letter values, with no letter worth 9, follow the table in Cheiro's Book of Numbers (1926). Numerology turns a person's name and date of birth into numbers, as described by Encyclopaedia Britannica. 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: Name checker, Baby names.
- Used for: Business naming tools, Astrologer platforms, Numerology apps.
- Free tools: Name numerology calculator.
- Guides: Quickstart, Conventions, Errors, Changelog, Chaldean vs Pythagorean numerology.