How to choose a numerology API: 10 things to check before you integrate

Numerology APIs look interchangeable: send a name and a birthdate, get numbers back. They aren’t. Two APIs can return different destiny numbers for the same person, and both can be “right” according to different traditions. What matters is whether the provider tells you which tradition it follows, and whether it will keep following it.

This checklist works for any provider. We’ve included how the Simple Numerology API answers each question, but test every candidate the same way.

1. Are the conventions documented?

Ask the questions where numerology sources disagree:

• Is Y a vowel, a consonant, or does it depend on context?
• Do master numbers 11, 22 and 33 survive reduction?
• Are names summed whole, or reduced name by name first?
• Do middle names count toward the full-name numbers?
• How are accents handled? Is “María” read as “maria”, or is the í dropped?

If the documentation doesn’t answer these, you’ll find out the answers from user complaints. Simple Numerology API: every default is documented, and the contested ones (the Y rule and the reduction method) can be set per request.

2. Will the numbers ever change?

Most apps store charts. If the provider changes a convention, your stored charts silently disagree with new ones. Look for an explicit versioning policy and a way to pin a version. Here: conventions are frozen as part of the contract, requests can pin a version with the Numerology-Version header, and every response echoes the conventions that produced it.

3. Is it deterministic?

The same input should always produce the same output, with no model and no randomness. Only then can you cache a chart forever, which matters for both cost and latency. Test it: send the same request twice and compare the JSON.

4. What happens to the names you send?

You are sending personal data: full names and dates of birth. Check whether the provider stores request bodies, logs them, or puts names in the URL, where they end up in access logs. Here: nothing is stored or logged, and names travel only in the request body.

5. Are the response types honest?

Look at the schema and ask whether a “number” field can hold 11, 22 or 33, whether hidden passion can be a tie, and whether karmic debts arrive as an array. An API that squeezes everything into a single digit is either losing information or hiding it. See master numbers and your integer column.

6. How does it fail?

Send an impossible date such as 1990-02-30. A good API returns a 4xx with a machine-readable code and the name of the bad parameter. Then exceed the quota: you want a clear status code and quota headers, not a silent truncation or an HTML error page. Here: every error has the same shape (type, code, param, request_id), and running out of quota returns 402 with X-Quota-* headers.

7. Is there an OpenAPI spec?

An OpenAPI document lets you generate a typed client in any language, import the API into Postman, or point an AI coding assistant at it. Here: OpenAPI 3.1, a Postman collection and quickstarts for Python and JavaScript. See generating a client.

8. Can you try it properly for free?

A free tier should cover the real API, not a subset of fields, and shouldn’t need a card. Here: the free plan is 100 charts a month on every endpoint, with no card.

9. Does it handle real names?

Your users are not all called John Smith. Send “María García López”, a hyphenated “Jean-Luc”, and a name in another script, and look at which letters were actually counted. An API that silently drops the í, or every letter of a Cyrillic name, returns a confident chart computed from part of the name. Here: accents are folded (María counts as maria), Russian Cyrillic is valued natively, transliteration to Latin is one option away, and every chart returns computed_name, the letters it was computed from, so you can see what counted.

10. Is it one call or twenty?

Some APIs expose one endpoint per number: life path here, destiny there, soul urge somewhere else. A full profile then costs a dozen requests, a dozen chances to fail halfway, and a dozen charges against your quota. Check what a single request returns, and whether there is a batch endpoint for backfills. Here: one request returns all 47 fields, from life path to planes of expression, and a batch call returns up to 100 charts, charged all or nothing.

A five-minute evaluation script

Run the same checks against every candidate:

# Determinism: two identical requests should produce identical JSON
for i in 1 2; do
  curl -s -X POST "$API/v1/charts/pythagorean" -H "X-API-Key: $KEY" \
    -H 'content-type: application/json' \
    -d '{"first_name":"Lynn","last_name":"Kylie","birthdate":"1980-12-08"}' \
    | shasum
done

# Life path for 1980-12-08 should be 2, not 11 (the straight-sum shortcut)
# "Lynn" tests the Y rule; an accented name such as "José" tests folding

Compare the answers with the life path method and the Y rule. A provider that gets 1980-12-08 wrong is using the shortcut, and most of its other numbers are probably built the same way.