NUMEROLOGY · JSON REST API

Numerology API

Convert a birth date and optional name into a documented set of symbolic numbers. The result exposes compound totals, reduced values and the normalized name used in the calculation.

AvailablePOST /v1/numerology/reading

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Calculate Pythagorean or Chaldean name numbers, life path and personal cycles with explicit reduction and transliteration rules. View real JSON.

01

Pythagorean or Chaldean letter-value systems

02

Life path, birthday, expression, soul urge and personality numbers

03

Optional preservation of master numbers 11, 22 and 33

04

Personal year, month and day when target_date is supplied

Send

  • A Gregorian date and optional name
  • system: pythagorean or chaldean; optional preserve_master_numbers
  • Optional target_date and a supported interpretation locale

Receive

  • numbers with compound, value, root and master fields
  • romanized_name and transliteration method
  • Original number-type-specific symbolic explanations
ACTUAL CALCULATED NUMBERS

Read the calculation.

Every value below comes from this result. The normalized sample name is ALEX.

life path9

Compound 27 · root 9

birthday3

Compound 21 · root 3

expression6

Compound 15 · root 6

soul urge6

Compound 6 · root 6

personality9

Compound 9 · root 9

personal year9

Compound 18 · root 9

personal month2

Compound 20 · root 2

personal day1

Compound 19 · root 1

INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/numerology/reading
{
  "locale": "en",
  "date": "1990-05-21",
  "name": "Alex",
  "target_date": "2026-11-17"
}
Response JSON · selected fields
{
  "request_id": "61fd7c13f8dee1ffab9e035be42ae67a",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "system": "pythagorean",
    "birth_date": "1990-05-21",
    "romanized_name": "ALEX",
    "numbers": {
      "life_path": {
        "compound": 27,
        "value": 9,
        "root": 9,
        "master": false
      },
      "birthday": {
        "compound": 21,
        "value": 3,
        "root": 3,
        "master": false
      },
      "expression": {
        "compound": 15,
        "value": 6,
        "root": 6,
        "master": false
      },
      "soul_urge": {
        "compound": 6,
        "value": 6,
        "root": 6,
        "master": false
      },
      "personality": {
        "compound": 9,
        "value": 9,
        "root": 9,
        "master": false
      },
      "personal_year": {
        "compound": 18,
        "value": 9,
        "root": 9,
        "master": false
      },
      "personal_month": {
        "compound": 20,
        "value": 2,
        "root": 2,
        "master": false
      }
    },
    "method": {
      "version": "celestack-numerology-v1",
      "transliteration": "AnyAscii 0.3.3; uppercase ASCII A-Z; punctuation/digits removed",
      "vowels": "AEIOU; Y is a consonant",
      "life_path": "whole Gregorian birth-date digit sum",
      "master_numbers": [
        11,
        22
      ],
      "personal_cycles": "Gregorian calendar-year convention, single-digit reduction",
      "interpretation": "symbolic, not a scientifically validated personality assessment"
    }
  },
  "interpretation": {
    "locale": "en",
    "kind": "numerology/reading",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 8,
      "selected_facts": 8,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "numerology.life_path",
        "title": "Life path",
        "text": "Calculated number: 9. A useful reflective theme is completion.",
        "source": {
          "id": "numerology.life_path",
          "type": "numerology_number",
          "number_type": "life_path",
          "compound": 27,
          "value": 9,
          "root": 9,
          "master": false
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 1
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/numerology/reading' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: numerology-api-example-001' \
+  --data '{
  "locale": "en",
  "date": "1990-05-21",
  "name": "Alex",
  "target_date": "2026-11-17"
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • A numerology profile screen
  • Transparent name-number comparisons
  • Personal-cycle content with an explicit reference date

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • Names are normalized through AnyAscii to uppercase A–Z. Different transliteration choices can change name numbers.
  • The life path uses the whole-date digit sum; Y is treated as a consonant. These are explicit school choices.
  • Numerology is not a scientifically validated personality or outcome assessment.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Which name spelling is calculated?

The service returns romanized_name after AnyAscii transliteration and uppercase A–Z filtering. Inspect it before presenting the result, especially for non-Latin names.

Are master numbers preserved?

The default preserves 11, 22 and 33 in the documented profile. Set preserve_master_numbers to false for ordinary reduction. Personal cycles use single digits.

How do I get personal year and day numbers?

Include target_date. The response then adds personal-year, personal-month and personal-day fields using the stated Gregorian calendar-year convention.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 1 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API