Calculator Endpoints

Quick astrological and numerological calculations at 1 credit each.

Perfect for lightweight integrations and quick lookups.

---

Life Path Number Calculator

Calculate the Life Path number from a birth date.

Endpoint

POST /api/v1/calculators/life-path

Pricing

1 credit - Fixed cost

Request Body

{
  "birthDate": "1990-12-25"  // Required: YYYY-MM-DD
}

Response Example

{
  "success": true,
  "data": {
    "lifePathNumber": 9,
    "calculation": "1+9+9+0+1+2+2+5 = 29 → 2+9 = 11 → 1+1 = 2",
    "description": {
      "number": 9,
      "title": "The Humanitarian",
      "keywords": ["Compassionate", "Idealistic", "Generous", "Wise"],
      "strengths": "Compassionate and altruistic...",
      "challenges": "Can be overly idealistic...",
      "lifePurpose": "To serve humanity..."
    }
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1999
  }
}

Use Cases

• Numerology apps
• Quick personality insights
• Birth date validation
• User onboarding features

---

Big Three Calculator

Calculate the Sun, Moon, and Rising signs (the "Big Three") from complete birth data.

Endpoint

POST /api/v1/calculators/big-3

Pricing

1 credit - Fixed cost

Request Body

{
  "birthDate": "1990-12-25",
  "birthTime": "14:30",
  "city": "New York",
  "country": "USA",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "timezone": "America/New_York"
}

Response Example

{
  "success": true,
  "data": {
    "sun": {
      "sign": "Capricorn",
      "degree": 3,
      "house": 10,
      "keywords": "Ambitious, Disciplined, Responsible",
      "description": "Your core self is determined and strategic...",
      "element": "Earth",
      "modality": "Cardinal"
    },
    "moon": {
      "sign": "Cancer",
      "degree": 22,
      "house": 4,
      "keywords": "Nurturing, Sensitive, Intuitive",
      "description": "Deeply emotional and intuitive...",
      "element": "Water",
      "modality": "Cardinal"
    },
    "rising": {
      "sign": "Aries",
      "degree": 15,
      "keywords": "Dynamic, Direct, Energetic",
      "description": "You come across as confident and action-oriented...",
      "element": "Fire",
      "modality": "Cardinal"
    },
    "birthInfo": {
      "date": "1990-12-25",
      "time": "14:30",
      "location": "New York, USA"
    }
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1998
  }
}

Use Cases

• Complete personality assessments
• Astrology learning apps
• Quick astrological profiles
• User onboarding features

---

Natal Chart Calculator

Generate a complete natal chart with planets, houses, and aspects.

Endpoint

POST /api/v1/calculators/natal-chart

Pricing

1 credit - Fixed cost (99% cheaper than full blueprint!)

Request Body

{
  "birthDate": "1990-12-25",
  "birthTime": "14:30",
  "city": "New York",
  "country": "USA",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "timezone": "America/New_York"
}

Response Example

{
  "success": true,
  "data": {
    "chart": {
      "celestialBodies": {
        "sun": { "sign": "Sagittarius", "degree": 3.5, "house": 10 },
        "moon": { "sign": "Cancer", "degree": 22.5, "house": 4 },
        "mercury": { "sign": "Sagittarius", "degree": 15.2, "house": 10 },
        // ... all planets
      },
      "houses": [
        { "number": 1, "sign": "Virgo", "degree": 8.2 },
        // ... all 12 houses
      ],
      "aspects": [
        {
          "planet1": "SUN",
          "planet2": "MOON",
          "type": "square",
          "orb": 1.2,
          "applying": true
        }
        // ... all major aspects
      ]
    }
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1997
  }
}

What's Included

• All 10 planets + Chiron, North/South Nodes
• All 12 house cusps
• Major aspects (conjunction, opposition, trine, square, sextile)
• Minor aspects (quincunx, semi-sextile, etc.)
• Retrograde status for all planets
• Exact degrees for precision

What's NOT Included

• AI interpretations (use blueprint generation for that)
• Human Design data
• Numerology data
• Pre-formatted text descriptions

Use Cases

Custom Interpretation Layers:

• Build your own interpretation engine
• Create unique astrological insights
• Develop proprietary algorithms

Chart Comparison Tools:

• Synastry analysis
• Composite charts
• Transit overlays

Visualization Apps:

• Interactive chart wheels
• Aspect pattern recognition
• Custom chart displays

Educational Platforms:

• Astrology learning tools
• Chart calculation practice
• Technical astrology study

---

Comparison: Calculators vs. Blueprint Generation

---

Error Responses

{
  "error": "Invalid birth date",
  "message": "Birth date must be in YYYY-MM-DD format"
}

{
  "error": "Birth location required",
  "message": "City, country, latitude, longitude, and timezone are required"
}

{
  "error": "Insufficient credits",
  "message": "This calculation costs 1 credit",
  "required": 1,
  "available": 0
}