Compatibility Score¶

The Compatibility Score analyzes 9 core numerology numbers from two individuals (Life Path, Heart's Desire, Personality, etc.) and returns:

• Individual numerology profiles
• Pairwise compatibility scores
• Weighted overall score (0–100)
• Relationship insight

Perfect for dating, marriage, business, or friendship analysis. Master Numbers: Fully supported (11, 22, 33).

Endpoint¶

Required Headers¶

• X-API-Key: YOUR_API_KEY
• Host: api.numerologyapi.com
• Content-Type: application/json (POST only)

Create and manage API keys in the Numerology API dashboard.

Parameters¶

Person 1¶

Person 2¶

Add the optional lang query parameter to localize responses. Supported values: en, es, de, fr, pt.

Example Requests¶

GET Request¶

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/compatibility-score?first_name_1=John&last_name_1=Doe&first_name_2=John&last_name_2=Doe&dob_1=1992-07-16&dob_2=1992-07-16&middle_name_1=&middle_name_2=&lang=en" \
  --header "X-API-Key: YOUR_API_KEY"

POST Request (JSON Body)¶

curl --request POST \
  --url "https://api.numerologyapi.com/api/v1/compatibility-score?lang=en" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "first_name_1": "John",
  "last_name_1": "Doe",
  "first_name_2": "John",
  "last_name_2": "Doe",
  "dob_1": "1992-07-16",
  "dob_2": "1992-07-16",
  "middle_name_1": "",
  "middle_name_2": ""
}'

Response Example¶

{
  "person_1": {
    "full_name": "John Doe",
    "initials": "JD",
    "dob": "1992-07-16",
    "life_path": 8,
    "heart_desire": 8,
    "personality": 9,
    "hidden_passion": [
      5,
      6
    ],
    "destiny_number": 8,
    "attitude_number": 5,
    "subconscious_self_number": 5,
    "balance_number": 5,
    "rational_thought_number": 9
  },
  "person_2": {
    "full_name": "John Doe",
    "initials": "JD",
    "dob": "1992-07-16",
    "life_path": 8,
    "heart_desire": 8,
    "personality": 9,
    "hidden_passion": [
      5,
      6
    ],
    "destiny_number": 8,
    "attitude_number": 5,
    "subconscious_self_number": 5,
    "balance_number": 5,
    "rational_thought_number": 9
  },
  "compatibility_scores": {
    "life_path_score": 80,
    "heart_desire_score": 80,
    "personality_score": 85,
    "hidden_passion_score": 95,
    "destiny_number_score": 80,
    "attitude_number_score": 95,
    "subconscious_self_score": 95,
    "balance_number_score": 95,
    "rational_thought_score": 85,
    "overall_score": 86.8,
    "overall_insight": "Very strong & harmonious connection. Your energies flow together with grace and mutual support. This is a relationship that feels like 'coming home' — powerful synergy with only gentle adjustments needed."
  },
  "_enterprise": {
    "client": "The Numerology API",
    "plan": "Enterprise",
    "request_id": "ced3a432226491dc",
    "quota": "unlimited",
    "usage_tracking": true
  },
  "_api_metadata_": {
    "api_name": "The Numerology API by Dakidarts®",
    "api_version": "0.1.1",
    "endpoint_name": "compatibility_score",
    "endpoint_description": "Computes numerology compatibility score between two individuals.",
    "developer": "Dakidarts®",
    "copyright": "© 2026 Dakidarts®. All rights reserved.",
    "documentation_url": "https://docs.numerologyapi.com/",
    "response_timestamp": "2026-02-28T07:36:26.749083+01:00",
    "data_source": "Internal Engine / Astro Numerology Interpretation Engine (ANIE)",
    "cacheable_status": true,
    "report_issue": "https://github.com/dakidarts/the-numerology-api/issues",
    "response_language": "en",
    "supported_languages": [
      "en",
      "es",
      "de",
      "fr",
      "pt"
    ],
    "notes": ""
  }
}

Scoring Algorithm¶

The compatibility scoring algorithm uses a multi-layered approach that combines numerological wisdom with mathematical precision:

1. Root Number Mapping: All numbers (including Master Numbers 11, 22, 33) are mapped to their root vibrations (e.g., 11→2, 22→4, 33→6). Calculations use these root values for compatibility assessment.

2. Numerological Pair Definitions: Specific number pairs known for strong compatibility in numerology are assigned predetermined base scores. For example:

   • (1, 5) and (5, 1): 85 (Adventure-driven combination)
   • (1, 9) and (9, 1): 75 (Leadership meets humanitarianism)
   • (2, 6) and (6, 2): 90 (Nurturing partnership)

3. Fallback Calculation: If a pair is not explicitly defined, a standard formula is used: base_score = max(25, 100 - root_diff * 10), ensuring a minimum baseline compatibility of 25%.

4. Master Number Resonance Bonus: Pairs involving Master Numbers receive additional points if their root values are identical (+15) or adjacent (+8), reflecting their intensified spiritual energy.

5. Exact Match Bonus: When both original numbers (before root reduction) are identical, an extra +10 bonus is applied, acknowledging the resonance of shared vibration.

6. Final Calculation: The total score is the sum of the base score, master bonus, and exact match bonus, capped at 100%.

Scoring Weights¶

Overall Score = Weighted average of individual scores + Intensity Factor. Intensity Factor: A small boost (up to +5%) is applied if either person's Life Path or Heart's Desire is a Master Number, reflecting their potential for deeper spiritual connection.

Overall Insight Levels¶

Open Dashboard