Numerology API quickstart: make your first call

You need an API key, a name in English letters and a birth date. No birth time or place is needed. Any server that can send HTTPS requests works: curl, Node.js 18 or later, Python with the requests package, or PHP with curl.

1. Get a key

Already use the Astrology API? Use the same key. One key works for both APIs. If you are new, create an account, then open the API keys page and create a key. The full key is shown only once, so copy it somewhere safe. Keys start with afa_test_ or afa_live_.

Test keys work as soon as you create them and are never billed. They allow 1,000 calls a month, shared by both APIs. On a test key, numerology answers only for the sample people. They are John Doe (born August 15, 1990) and Jane Doe (born March 22, 1992). See test keys.

No key yet? The free numerology calculator runs this same call, POST /v1/profile, with no key, for any name and date. The API reference shows a real recorded answer for every endpoint.

Save your key as an environment variable on your server. The examples below read it from ASTROLOGY_API_KEY, the same name the astrology examples use.

# macOS and Linux
export ASTROLOGY_API_KEY="afa_test_..."

# Windows PowerShell
$env:ASTROLOGY_API_KEY="afa_test_..."

2. Make your first call

Send a name and a birth_date. Both are required. Write the name in English letters, the way the person uses it. Write the date as YYYY-MM-DD. This example is John Doe, born on August 15, 1990.

# 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"}'

Call the API from your server, not from a web page or mobile app, so the key stays private. The JavaScript example uses await at the top level, so save it as a .mjs file.

Prefer an API client? The Postman collection has every endpoint with the sample people filled in, so a test key answers each one. Import it into Postman, Insomnia, Bruno or Hoppscotch. Then set the apiKey variable to your key.

3. Read the response

A successful call returns 200 and John Doe’s numbers as JSON. Three numbers come first:

• The mulank (birth day number, also called the driver number) comes from the day of birth. The 15th becomes 1 + 5 = 6.
• The bhagyank (destiny number, also called the conductor number) adds every digit of the whole birth date.
• The name number adds up the values of the letters in the name.

Each number has a planet and a short reading. Here is a short part of the answer:

{
  "mulank": {
    "number": 6,
    "planet": "Venus",
    "reading": "You care about home, family and things that look good. People feel welcome around you. Watch for spending too much on comfort."
  },
  "bhagyank": {
    "number": 6,
    "total": 33,
    "master": true,
    "planet": "Venus"
  },
  "name_number": {
    "chaldean": {
      "name": "John Doe",
      "number": 7,
      "planet": "Ketu"
    }
  }
}

John Doe’s birth date adds up to 33 before it is cut down to one digit. 33 is a master number. So the bhagyank keeps total 33 and sets master to true, while its number is still 6.

The full answer has more. It has the Lo Shu grid, and the lucky day, colors and dates. It also has the gemstone and mantra, and the name number in the Pythagorean system next to the Chaldean one. John Doe’s name number is 7 in Chaldean and 8 in Pythagorean. Chaldean vs Pythagorean numerology explains why the two differ.

Common first-call errors

Every error comes back as JSON with a code, a message and, for a bad field, a field. A first call can get these:

• 401 unauthorized with the message Provide a key as "Authorization: Bearer <key>" or "X-API-Key: <key>". The key variable is empty. Run the export line again in the same terminal window.
• 401 unauthorized with The API key is invalid. The key is mistyped or cut short. Copy it again.
• 422 invalid_input with Field required and "field": "birth_date". The date is missing. A date like 08/15/1990 is refused too, with the same field. Send 1990-08-15.
• 422 invalid_input with "field": "name". The name is in another script, such as Hindi. The API does not change it into English letters for you, because each spelling gives a different number. Ask the user how they spell their name in English.
• 403 sample_charts_only on a test key. The call was about someone other than the sample people. Send John Doe or Jane Doe, or use a live key.

Every code is in the errors guide.

Next steps

• Browse every endpoint in the API reference and send test requests with your key.
• Read how authentication and rate limits work.
• Check the conventions for the two number systems, master numbers, names and dates.
• Need the Western numbers? POST /v1/western returns the life path number and the rest from the same name and birth date. John Doe’s life path is 6.
• See every number in one document: the sample numerology report for John Doe.
• Follow new endpoints and fixes in the changelog.