Numerology API for Python

Your first chart

Get a free key from the pricing section, export it as NUMEROLOGY_API_KEY, then:

import os
import requests

API = "https://simplenumerologyapi.com"
HEADERS = {"X-API-Key": os.environ["NUMEROLOGY_API_KEY"]}

chart = requests.post(
    f"{API}/v1/charts/pythagorean",
    headers=HEADERS,
    json={"first_name": "María", "middle_name": "Stefania", "last_name": "García López", "birthdate": "1990-03-12"},
    timeout=10,
).json()

print(chart["life_path_number"])  # 7
print(chart["destiny_number"])  # 5
print(chart["soul_urge_number"])  # 4
print(chart["karmic_debt_numbers"])  # [13]

That one call returns 47 fields: the core numbers, karmic lessons and debts, hidden passion, planes of expression, pinnacles, challenges and life cycles. The chart object reference documents every field.

The JSON response

Here is the start of the response:

{
  "object": "chart",
  "system": "pythagorean",
  "person": {
    "first_name": "María",
    "middle_name": "Stefania",
    "last_name": "García López",
    "birthdate": "1990-03-12"
  },
  "life_path_number": 7,
  "destiny_number": 5,
  "soul_urge_number": 4,
  "personality_number": 1,
  "maturity_number": 3,
  "karmic_debt_numbers": [13],
  "hidden_passion_number": [1],
  "pinnacles": [
    {"stage": 1, "number": 6, "from_age": 0, "to_age": 29},
    {"stage": 2, "number": 4, "from_age": 30, "to_age": 38},
    {"stage": 3, "number": 1, "from_age": 39, "to_age": 47},
    {"stage": 4, "number": 4, "from_age": 48, "to_age": null}
  ],
  "…": "more fields"
}

Two things to handle in your models: number fields can hold the master numbers 11, 22 or 33 as well as 1–9, and hidden_passion_number is a list because ties are allowed.

Cycles and compatibility

Every endpoint takes a JSON body in the same way. A Session keeps the connection open between calls, so only the first one waits for the TCP and TLS handshakes:

session = requests.Session()


def post(path, body):
    r = session.post(f"{API}{path}", headers=HEADERS, json=body, timeout=10)
    r.raise_for_status()
    return r.json()


post("/v1/cycles", {"birthdate": "1990-03-12", "date": "2026-09-26", "years_ahead": 3})

post(
    "/v1/compatibility",
    {
        "a": {"first_name": "Ana", "last_name": "Smith", "birthdate": "1990-01-01"},
        "b": {"first_name": "Luis", "last_name": "Wu", "birthdate": "1985-05-05"},
    },
)

Batch requests

Send up to 100 people in a single request. A batch counts as one request against the rate limit and one chart per person against the quota.

result = post(
    "/v1/charts/batch",
    {
        "charts": [
            {"first_name": "Ana", "last_name": "Smith", "birthdate": "1990-01-01"},
            {"first_name": "Luis", "last_name": "Wu", "birthdate": "1985-05-05"},
        ]
    },
)
for item in result["data"]:
    print(item["index"], item["chart"]["life_path_number"])

Errors and retries

Every error has the same JSON shape, with a stable code, the offending param and a request_id:

r = requests.post(
    f"{API}/v1/charts/pythagorean",
    headers=HEADERS,
    timeout=10,
    json={"first_name": "Ana", "last_name": "Smith", "birthdate": "1990-02-30"},
)
if not r.ok:
    err = r.json()["error"]
    print(r.status_code, err["code"], err.get("param"))  # param is "birthdate"

Retry 429, 500, 502, 503 and 504 with backoff, and wait for Retry-After when the API sends one. Charts are pure computations, so a retry is always safe. A 402 means the month’s quota is used up. The X-Quota-Remaining header on every response tells you how much is left.

Using it in Django, Flask or FastAPI

Call the API from your server, never from the browser: keys are server credentials and the API sends no CORS headers. Because a chart never changes for the same input, you can cache it indefinitely, keyed on the name, the birthdate and the conventions object in the response. Most apps compute a chart once at sign-up and store it next to the user.

Frequently asked questions

Is there a free numerology API for Python?

Yes. The free plan includes 100 charts a month with every endpoint and no card.

Do I need a special library to use the API from Python?

No. It is a JSON REST API: one POST with an X-API-Key header. requests, httpx or the standard library’s urllib all work.

Which numerology system does it use?

Pythagorean, on /v1/charts/pythagorean. The calculation conventions (whether Y is a vowel, how names reduce) are fixed and documented, and two of them can be changed per request.

Can I calculate a life path number without a name?

The chart endpoint needs a name because most fields come from it. For numbers based only on the date of birth (personal year, month and day), use /v1/cycles, which takes just a birthdate.