NUMEROLOGY · JSON REST API

Numerology Compatibility API

Generate two consistent symbolic number profiles and compare the fields they share. The response keeps both original calculations inspectable so your product can explain the basis of each comparison.

AvailablePOST /v1/numerology/compatibility

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

BUILD AROUND THE DATA

What this API provides.

Compare two documented numerology profiles with source-linked number comparisons. Preview real output without implying a relationship success score.

01

Two people evaluated under the same selected system

02

Birth-date and optional name-based number profiles

03

Shared master-number and target-date options

04

Source-linked comparisons instead of a relationship probability

Send

  • person_a and person_b, each with date and optional name
  • A shared Pythagorean or Chaldean system
  • Optional target_date, preserve_master_numbers and locale

Receive

  • The two underlying number profiles
  • Structured comparisons of available number types
  • Symbolic explanations with their source fact identifiers
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/compatibility
{
  "locale": "en",
  "person_a": {
    "date": "1990-05-21",
    "name": "Alex"
  },
  "person_b": {
    "date": "1992-02-10",
    "name": "Sam"
  },
  "target_date": "2026-11-17"
}
Response JSON · selected fields
{
  "request_id": "4c18fd51d8e6c2e54d6be2173c28f422",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "person_a": {
      "locale": "en",
      "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
        }
      },
      "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"
      }
    },
    "person_b": {
      "locale": "en",
      "system": "pythagorean",
      "birth_date": "1992-02-10",
      "romanized_name": "SAM",
      "numbers": {
        "life_path": {
          "compound": 24,
          "value": 6,
          "root": 6,
          "master": false
        },
        "birthday": {
          "compound": 10,
          "value": 1,
          "root": 1,
          "master": false
        },
        "expression": {
          "compound": 6,
          "value": 6,
          "root": 6,
          "master": false
        },
        "soul_urge": {
          "compound": 1,
          "value": 1,
          "root": 1,
          "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"
      }
    },
    "comparisons": [
      {
        "fact_id": "compatibility.numerology.life_path",
        "number_type": "life_path",
        "a": 9,
        "b": 6
      },
      {
        "fact_id": "compatibility.numerology.expression",
        "number_type": "expression",
        "a": 6,
        "b": 6
      }
    ],
    "score": null,
    "method": {
      "version": "celestack-numerology-comparison-v1",
      "score": "No success probability; compares symbolic themes only"
    }
  },
  "interpretation": {
    "locale": "en",
    "kind": "numerology/compatibility",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 4,
      "selected_facts": 4,
      "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": "compatibility.numerology.life_path",
        "title": "Life path",
        "text": "The calculated values are 9 and 6. Different symbolic themes appear; discuss preferences without ranking either person.",
        "source": {
          "id": "compatibility.numerology.life_path",
          "type": "numerology_comparison",
          "number_type": "life_path",
          "a": 9,
          "b": 6,
          "relation": "different_themes"
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 5
}

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/compatibility' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: numerology-compatibility-api-example-001' \
+  --data '{
  "locale": "en",
  "person_a": {
    "date": "1990-05-21",
    "name": "Alex"
  },
  "person_b": {
    "date": "1992-02-10",
    "name": "Sam"
  },
  "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 two-person reflective profile
  • Side-by-side number cards
  • A second symbolic comparison alongside synastry

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.

  • The comparison is not a validated match score or forecast of relationship success.
  • Name-derived fields are absent when a name is omitted; missing information is not fabricated.
  • Transliteration and reduction conventions are shared with the single-person numerology endpoint.

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.

Does it return a compatibility percentage?

No. It returns numerical profiles and symbolic comparisons. A measured relationship success probability is not part of this system.

Can I compare people without their names?

Yes. Supply both birth dates. Date-based numbers remain available, while unavailable name-derived fields are null rather than invented.

Are options applied consistently to both people?

Top-level system, master-number and target-date options are shared. The output includes the underlying profiles so you can inspect the calculation basis.

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. 5 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