Adding numerology to your app in about five lines

If you are building an astrology app, a dating product, a personalised gift shop, or anything that takes a name and a birthday, numerology is a cheap feature to add and a surprisingly annoying one to build.

The arithmetic is trivial. The conventions are not — and getting one wrong shifts every chart you produce.

The request

One POST, one header:

curl -X POST https://simplenumerologyapi.com/v1/charts/pythagorean \
  -H 'content-type: application/json' \
  -H 'X-API-Key: nk_…' \
  -d '{
    "first_name": "María",
    "middle_name": "Stefania",
    "last_name": "García López",
    "birthdate": "1990-03-12"
  }'

In Python:

import os, requests

chart = requests.post(
    "https://simplenumerologyapi.com/v1/charts/pythagorean",
    headers={"X-API-Key": os.environ["NUMEROLOGY_KEY"]},
    json={
        "first_name": "María",
        "last_name": "García López",
        "birthdate": "1990-03-12",
    },
    timeout=10,
).json()

print(chart["life_path_number"])

That is the whole integration. Retry 429 and 5xx responses, waiting for Retry-After when the API sends it. The full contract is published as OpenAPI if you’d rather generate a typed client.

Give each environment its own key, so one can be rolled or revoked without touching the others.

Send the whole name

The most common integration error is passing a display name.

Middle names and compound surnames are part of the calculation, not decoration. "María García López" and "María García" are different charts — not slightly different, different. If your signup form collects a single “full name” field, split it deliberately rather than dropping what does not fit.

Accents are handled for you: í normalises to i before lookup. Spaces, hyphens and apostrophes contribute nothing, so O'Brien and OBrien agree.

Three response shapes that surprise people

1. A field typed integer can return two digits. Master numbers 11, 22 and 33 halt reduction. If you have a lookup table keyed 1–9, it will raise on a master number eventually.

LABELS.get(chart["life_path_number"], "Unknown")  # not LABELS[...]

2. hidden_passion_number is an array. Ties are canonical in the system, not an error condition, so two numbers can occur equally often and both are returned.

3. full_name_number_counts is a list. One {"number": 1, "count": 7} entry for each digit from 1 to 9, in order, with a count of 0 for digits the name lacks.

Cache it — the output never changes

Charts are deterministic. The same name, date and options produce the same 47 fields forever: no model, no randomness, and no drift — a rule change can only arrive as a new, opt-in API version.

That makes the cache key trivial:

key = f"chart:{first}:{middle}:{last}:{birthdate}:{y_rule}:{name_reduction}".lower()

If you use the default conventions, the last two parts are constant. Cache with no expiry. A user’s chart is computed once, ever. For most products this means the API is called on signup and essentially never again — which is also the cheapest way to stay inside a quota.

Handle the failures

Every error has the same shape — {"error": {"type", "code", "message", "param", "doc_url", "request_id"}} — so one handler covers them all:

Status	Meaning	Retry?
401	Missing, revoked or invalid key	No — fix the key
402	Monthly quota exhausted	No — upgrade, enable overage, or wait for reset
422	Validation failed (param names the field)	No — fix the input
429	Rate limited	Yes, after Retry-After seconds
5xx	Our side	Yes, with backoff — quote request_id if it persists

Every response carries X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset, so you can warn before a batch job walks into a wall rather than discovering it halfway through.

You also get an email at 80% and at 100% of the quota. Cancelling a paid plan drops you to the free quota rather than revoking your keys, so an expired card never hard-breaks a live integration.

What you get back

47 fields: the core numbers (life path, destiny, soul urge, personality), derived numbers (maturity, balance, rational thought), karmic lessons and debts, the four planes of expression, bridges, and pinnacles, challenges and life cycles with their age brackets.

Start on the free tier: 100 charts a month, no card.