jyotish.today API v2
API Modules
Core Kundli & Planetary 3 Panchang & Muhurata 2 Dashas & Timing 1 Match Making (Kundli Milan) 1 Financial & Market Astrology 2 PDF Report Studio 1 Conversational AI Astrologer 1
AI-FIRST ONBOARDING

Prompt-to-Integrate (Cursor, Claude, Copilot)

AI Assistant Ready

Building with Cursor, Claude Code, GitHub Copilot, v0.dev, or Lovable? Copy this master prompt into your AI assistant, and it will generate the complete, working integration code automatically. 

You are an expert full-stack developer integrating the official Jyotish Today Vedic & Financial Astrology API into this project.

### BASE API CONFIGURATION
- Base URL: https://api.jyotish.today
- Auth Header: Authorization: Bearer YOUR_API_KEY
- Content-Type: application/json
- Precision: Swiss Ephemeris C-Engine (<50ms execution)
- Rate Limit: 1 credit = 1 calculation

### ESSENTIAL ENDPOINTS
1. Planetary Positions & Houses:
   POST https://api.jyotish.today/v2/planets
   Body: { "year": 1995, "month": 8, "day": 15, "hour": 14, "min": 30, "lat": 28.6139, "lon": 77.2090, "tzone": 5.5 }

2. Daily Panchang & Muhuratas:
   POST https://api.jyotish.today/v2/panchang
   Body: { "year": 2026, "month": 9, "day": 4, "lat": 28.6139, "lon": 77.2090, "tzone": 5.5 }

3. 36-Guna Kundli Milan:
   POST https://api.jyotish.today/v2/match_making/ashtakoot_points
   Body: { "male": { "year": 1995, "month": 8, "day": 15, "hour": 14, "min": 30, "lat": 28.61, "lon": 77.20 },
           "female": { "year": 1997, "month": 3, "day": 20, "hour": 9, "min": 15, "lat": 19.07, "lon": 72.87 } }

4. Conversational AI Astrologer (Zero-Hallucination):
   POST https://api.jyotish.today/v2/ai/chat
   Body: { "message": "User query", "birth_details": { ... }, "language": "en" }

### INSTRUCTIONS
Create a resilient service class or API client in this project matching these endpoints. Handle 429 quota exhaustion gracefully.
API v2 Specifications

Authentication & Request Format

Base Endpoint: https://api.jyotish.today

Standard Authentication Header: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Every response is wrapped in a consistent JSON envelope with { "status": "success"|"error", "data": {...}, "execution_ms": 18 }. Sign in to test live requests with your own API keys.

NEW: AI & LLM AGENTS

Model Context Protocol (MCP) Server

Cursor & Claude Ready

Connect Claude Desktop, Cursor IDE, Antigravity, or custom autonomous AI agents directly to Jyotish Today. The AI gains native tool capabilities for planetary charts, panchang, dashas, and matchmaking with zero custom code.

Claude Desktop Configuration
Add to claude_desktop_config.json:
{
  "mcpServers": {
    "jyotish-today": {
      "command": "node",
      "args": ["/path/to/jyotish-today/mcp-server/index.js"],
      "env": {
        "JYOTISH_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
Cursor IDE / AI Agent Config
Add to .cursor/mcp.json or Cursor Settings:
{
  "mcpServers": {
    "jyotish-today": {
      "command": "node",
      "args": ["/path/to/jyotish-today/mcp-server/index.js"],
      "env": {
        "JYOTISH_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
Plan Tier Included MCP Tools Concurrency Action
Free Sandbox get_planetary_positions, get_daily_panchang, get_vimshottari_dasha 2 req / sec Free Key
Developer Starter + calculate_kundli_milan, get_divisional_chart (D1 to D12) 10 req / sec Upgrade
Pro Commercial Full Suite + Financial Tools: get_financial_market_transits, get_sarvatobhadra_vedha, full D1–D60 30 req / sec Choose Pro
Enterprise Scale All Tools + Multi-Agent Swarm Concurrency 100+ req / sec Custom SLA
Zero-Hallucination Ephemeris: Every tool call is metered transparently at 1 tool call = 1 credit.
Official MCP Protocol Docs
NO-CODE WEB WIDGET

1-Line Embeddable AI Astrologer

Drop-In Ready

Add a turnkey, floating AI Astrologer chat bubble to any website, WordPress blog, or Shopify store in under 10 seconds. Visitors enter their birth details and receive authentic Vedic horoscope answers in Hindi or English.

Copy & Paste Code Snippet (before </body>): 
<script src="https://jyotish.today/v2/widget/ai-astrologer.js" 
        data-key="YOUR_API_KEY"
        data-brand="Acharya AI"
        data-theme="#2F3F8F"
        data-lang="hi"></script>
Zero Dependencies (~15KB)
Multi-language (Hindi & English)
Mobile Responsive Drawer
Metered at 5 credits / msg

Core Kundli & Planetary

3 endpoints
POST /v2/astrology/planets core

Calculates high-precision Nirayana (sidereal) planetary positions, signs, degrees, speed, retrograde flags, and Nakshatras using Swiss Ephemeris.

Payload Parameters
Param Type Required Description
year integer required Birth year (e.g. 1995)
month integer required Birth month (1-12)
day integer required Birth day (1-31)
hour integer required Birth hour (0-23)
min integer required Birth minute (0-59)
lat float required Latitude in decimal degrees (-90 to +90)
lon float required Longitude in decimal degrees (-180 to +180)
tzone float required Timezone offset from UTC (e.g. 5.5 for IST)
ayanamsha string optional Ayanamsha system: lahiri (default), raman, kp, yukteshwar
<50ms response 
{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14,
    "min": 30,
    "sec": 0,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5,
    "ayanamsha": "lahiri"
}
{
    "status": "success",
    "endpoint": "/v2/astrology/planets",
    "execution_ms": 18,
    "data": {
        "ascendant": {
            "sign": "Scorpio",
            "sign_id": 8,
            "degree": 14.28,
            "nakshatra": "Anuradha",
            "pada": 4
        },
        "planets": {
            "Sun": {
                "sign": "Leo",
                "degree": 28.14,
                "house": 10,
                "nakshatra": "Uttara Phalguni",
                "retrograde": false
            },
            "Moon": {
                "sign": "Aries",
                "degree": 12.05,
                "house": 6,
                "nakshatra": "Ashwini",
                "retrograde": false
            },
            "Mars": {
                "sign": "Libra",
                "degree": 5.42,
                "house": 12,
                "nakshatra": "Chitra",
                "retrograde": false
            },
            "Mercury": {
                "sign": "Virgo",
                "degree": 16.22,
                "house": 11,
                "nakshatra": "Hasta",
                "retrograde": false
            },
            "Jupiter": {
                "sign": "Scorpio",
                "degree": 18.3,
                "house": 1,
                "nakshatra": "Jyeshtha",
                "retrograde": false
            },
            "Venus": {
                "sign": "Leo",
                "degree": 2.1,
                "house": 10,
                "nakshatra": "Magha",
                "retrograde": false
            },
            "Saturn": {
                "sign": "Aquarius",
                "degree": 24.5,
                "house": 4,
                "nakshatra": "Purva Bhadrapada",
                "retrograde": false
            },
            "Rahu": {
                "sign": "Libra",
                "degree": 8.19,
                "house": 12,
                "nakshatra": "Swati",
                "retrograde": true
            },
            "Ketu": {
                "sign": "Aries",
                "degree": 8.19,
                "house": 6,
                "nakshatra": "Ashwini",
                "retrograde": true
            }
        }
    }
}
POST /v2/astrology/houses core

Calculates 12 Bhavas (House cusps, midpoints, ascendant/lagna, and planetary occupants) across standard house systems.

Payload Parameters
Param Type Required Description
year integer required Birth year
lat float required Latitude
lon float required Longitude
house_system string optional placidus (default), equal, sripati
<50ms response 
{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14,
    "min": 30,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/astrology/houses",
    "execution_ms": 22,
    "data": {
        "house_system": "Placidus",
        "ascendant": {
            "sign": "Scorpio",
            "degree": 14.28
        },
        "midheaven": {
            "sign": "Leo",
            "degree": 18.52
        },
        "houses": [
            {
                "house": 1,
                "sign": "Scorpio",
                "cusp": 14.28,
                "occupants": [
                    "Jupiter"
                ]
            },
            {
                "house": 2,
                "sign": "Sagittarius",
                "cusp": 12.14,
                "occupants": []
            },
            {
                "house": 4,
                "sign": "Aquarius",
                "cusp": 18.52,
                "occupants": [
                    "Saturn"
                ]
            },
            {
                "house": 6,
                "sign": "Aries",
                "cusp": 16.02,
                "occupants": [
                    "Moon",
                    "Ketu"
                ]
            },
            {
                "house": 10,
                "sign": "Leo",
                "cusp": 18.52,
                "occupants": [
                    "Sun",
                    "Venus"
                ]
            }
        ]
    }
}
POST /v2/astrology/divisional_chart kp

Generates any Vedic divisional chart (D1 Rashi, D9 Navamsha, D2 Hora, D3 Drekkana, D7 Saptamsha, D10 Dashamsha, D60 Shashtiamsha).

Payload Parameters
Param Type Required Description
chart_type string required D1, D2, D3, D7, D9, D10, D12, D16, D20, D24, D27, D30, D40, D45, D60
<50ms response 
{
    "chart_type": "D9",
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14,
    "min": 30,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/astrology/divisional_chart",
    "execution_ms": 19,
    "data": {
        "chart": "D9 - Navamsha",
        "ascendant": {
            "sign": "Pisces",
            "degree": 8.42
        },
        "planets": {
            "Sun": {
                "sign": "Cancer",
                "house": 5
            },
            "Moon": {
                "sign": "Aries",
                "house": 2
            },
            "Jupiter": {
                "sign": "Scorpio",
                "house": 9
            },
            "Saturn": {
                "sign": "Capricorn",
                "house": 11
            }
        }
    }
}

Panchang & Muhurata

2 endpoints
POST /v2/panchang/daily panchang

Daily Vedic calendar data: Vaar, Tithi, Nakshatra, Yoga, Karana, Sunrise, Sunset, Moonrise, Rahu Kaal, Yamaganda, Gulika.

Payload Parameters
Param Type Required Description
year integer required Target year
month integer required Target month
day integer required Target day
lat float required Location Latitude
lon float required Location Longitude
<50ms response 
{
    "year": 2026,
    "month": 9,
    "day": 2,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/panchang/daily",
    "execution_ms": 15,
    "data": {
        "date": "2026-09-02",
        "day": "Wednesday",
        "tithi": {
            "name": "Krishna Shashthi",
            "number": 21,
            "end_time": "18:42:10"
        },
        "nakshatra": {
            "name": "Krittika",
            "number": 3,
            "end_time": "21:15:30"
        },
        "yoga": {
            "name": "Harshana",
            "end_time": "14:10:00"
        },
        "karana": {
            "name": "Vanija",
            "end_time": "07:35:20"
        },
        "sunrise": "06:01:24",
        "sunset": "18:41:05",
        "rahu_kaal": {
            "start": "12:21:14",
            "end": "13:56:12"
        },
        "yamaganda": {
            "start": "07:36:12",
            "end": "09:11:10"
        },
        "gulika": {
            "start": "10:46:15",
            "end": "12:21:14"
        }
    }
}
POST /v2/panchang/choghadiya panchang

Computes daytime and nighttime Choghadiya auspicious intervals (Amrit, Shubh, Labh, Char, Rog, Kaal, Udveg).

Payload Parameters
Param Type Required Description
day integer required Target day
month integer required Target month
year integer required Target year
<50ms response 
{
    "year": 2026,
    "month": 9,
    "day": 2,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/panchang/choghadiya",
    "execution_ms": 12,
    "data": {
        "day_choghadiya": [
            {
                "muhurat": "Labh",
                "type": "auspicious",
                "start": "06:01",
                "end": "07:36"
            },
            {
                "muhurat": "Amrit",
                "type": "auspicious",
                "start": "07:36",
                "end": "09:11"
            },
            {
                "muhurat": "Kaal",
                "type": "inauspicious",
                "start": "09:11",
                "end": "10:46"
            },
            {
                "muhurat": "Shubh",
                "type": "auspicious",
                "start": "10:46",
                "end": "12:21"
            }
        ]
    }
}

Dashas & Timing

1 endpoints
POST /v2/dasha/major_vdasha dashas

Calculates 120-year Vimshottari Maha Dasha order, start dates, and end dates based on Moon nakshatra position.

Payload Parameters
Param Type Required Description
year integer required Birth year
lat float required Latitude
lon float required Longitude
<50ms response 
{
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14,
    "min": 30,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/dasha/major_vdasha",
    "execution_ms": 17,
    "data": {
        "balance_at_birth": "Ketu: 4 years, 8 months, 12 days",
        "dashas": [
            {
                "planet": "Ketu",
                "start": "1995-08-15",
                "end": "2000-04-27"
            },
            {
                "planet": "Venus",
                "start": "2000-04-27",
                "end": "2020-04-27"
            },
            {
                "planet": "Sun",
                "start": "2020-04-27",
                "end": "2026-04-27"
            },
            {
                "planet": "Moon",
                "start": "2026-04-27",
                "end": "2036-04-27"
            },
            {
                "planet": "Mars",
                "start": "2036-04-27",
                "end": "2043-04-27"
            }
        ]
    }
}

Match Making (Kundli Milan)

1 endpoints
POST /v2/match_making/ashtakoot_points matchmaking

Scores compatibility across all 8 Kootas (Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, Nadi) out of 36 Gunas.

Payload Parameters
Param Type Required Description
male object required {year, month, day, hour, min, lat, lon, tzone}
female object required {year, month, day, hour, min, lat, lon, tzone}
<50ms response 
{
    "male": {
        "year": 1994,
        "month": 5,
        "day": 20,
        "hour": 10,
        "min": 15,
        "lat": 28.6139,
        "lon": 77.209,
        "tzone": 5.5
    },
    "female": {
        "year": 1996,
        "month": 9,
        "day": 12,
        "hour": 18,
        "min": 45,
        "lat": 19.076,
        "lon": 72.8777,
        "tzone": 5.5
    }
}
{
    "status": "success",
    "endpoint": "/v2/match_making/ashtakoot_points",
    "execution_ms": 28,
    "data": {
        "total_points": 28.5,
        "maximum_points": 36,
        "result": "Good Match (Auspicious for Marriage)",
        "kootas": {
            "varna": {
                "received": 1,
                "max": 1,
                "desc": "Spiritual harmony"
            },
            "vashya": {
                "received": 2,
                "max": 2,
                "desc": "Mutual attraction"
            },
            "tara": {
                "received": 3,
                "max": 3,
                "desc": "Destiny & health"
            },
            "yoni": {
                "received": 4,
                "max": 4,
                "desc": "Biological compatibility"
            },
            "graha_maitri": {
                "received": 5,
                "max": 5,
                "desc": "Intellectual friendship"
            },
            "gana": {
                "received": 5,
                "max": 6,
                "desc": "Behavioral temperaments"
            },
            "bhakoot": {
                "received": 7,
                "max": 7,
                "desc": "Family welfare & prosperity"
            },
            "nadi": {
                "received": 1.5,
                "max": 8,
                "desc": "Genetic compatibility"
            }
        }
    }
}

Financial & Market Astrology

2 endpoints
POST /v2/financial/market_transit financial

Real-time planetary transits mapped against market indices, commodities, and equity sectors.

Payload Parameters
Param Type Required Description
year integer required Target year
month integer required Target month
day integer required Target day
<50ms response 
{
    "year": 2026,
    "month": 9,
    "day": 2,
    "hour": 9,
    "min": 15,
    "lat": 19.076,
    "lon": 72.8777,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/financial/market_transit",
    "execution_ms": 24,
    "data": {
        "market_session": "NSE / BSE India",
        "planetary_bias": "Mildly Bullish",
        "high_volatility_sectors": [
            "Banking",
            "Metals",
            "Energy"
        ],
        "transits": [
            {
                "planet": "Jupiter",
                "nakshatra": "Rohini",
                "element": "Earth",
                "bias": "Expansion / Inflow"
            },
            {
                "planet": "Mars",
                "nakshatra": "Chitra",
                "element": "Fire",
                "bias": "Volatile swings"
            }
        ]
    }
}
POST /v2/financial/sarvatobhadra financial

Computes the 81-square Sarvatobhadra Chakra nakshatra cross-aspects (Front, Left, Right, Special Vedha).

Payload Parameters
Param Type Required Description
year integer required Target year
<50ms response 
{
    "year": 2026,
    "month": 9,
    "day": 2,
    "hour": 9,
    "min": 15,
    "lat": 19.076,
    "lon": 72.8777,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/financial/sarvatobhadra",
    "execution_ms": 31,
    "data": {
        "vedhas": [
            {
                "planet": "Saturn",
                "aspects": "Left Vedha on Ashwini",
                "severity": "Strong"
            },
            {
                "planet": "Jupiter",
                "aspects": "Direct Front Vedha on Rohini",
                "severity": "Benefic"
            }
        ]
    }
}

PDF Report Studio

1 endpoints
POST /v2/report/full_report pdf

Comprehensive JSON payload containing full horoscope analysis, doshas, gemstones, dashas, and life predictions.

Payload Parameters
Param Type Required Description
name string required Client Name
gender string required male / female
<50ms response 
{
    "name": "Aarav Gupta",
    "gender": "male",
    "year": 1995,
    "month": 8,
    "day": 15,
    "hour": 14,
    "min": 30,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5
}
{
    "status": "success",
    "endpoint": "/v2/report/full_report",
    "execution_ms": 45,
    "data": {
        "client": {
            "name": "Aarav Gupta",
            "gender": "male"
        },
        "ascendant": "Scorpio",
        "moon_sign": "Aries",
        "nakshatra": "Ashwini",
        "gemstone_recommendation": {
            "primary": "Red Coral",
            "benefic": "Yellow Sapphire"
        },
        "doshas": {
            "mangal_dosha": false,
            "kaal_sarp": false
        }
    }
}

Conversational AI Astrologer

1 endpoints
POST /v2/ai/chat narrative

Authentic conversational Vedic Astrologer grounded in Swiss Ephemeris natal placements, running Vimshottari dashas, and current planetary transits. Metered at 5 credits per conversational turn.

Payload Parameters
Param Type Required Description
message string required User question in natural language (English or Hindi)
birth_details object required Natal coordinates {year, month, day, hour, min, lat, lon, tzone}
session_id string optional Optional ID from prior exchange for multi-turn conversational memory
language string optional en (English) or hi (Hindi Devanagari)
persona string optional acharya (Traditional Master), coach (Life Counselor), gemstone (Remedies)
<50ms response 
{
    "message": "When can I expect financial and career growth?",
    "birth_details": {
        "year": 1995,
        "month": 8,
        "day": 15,
        "hour": 14,
        "min": 30,
        "lat": 28.6139,
        "lon": 77.209,
        "tzone": 5.5
    },
    "language": "hi",
    "persona": "acharya"
}
{
    "status": "success",
    "endpoint": "/v2/ai/chat",
    "data": {
        "session_id": "conv_434cb7d0f273ac6f95ec",
        "reply": "\u0939\u0930\u093f \u0950! \u0906\u092a\u0915\u0940 \u0915\u0941\u0902\u0921\u0932\u0940 \u0935\u0943\u0936\u094d\u091a\u093f\u0915 \u0932\u0917\u094d\u0928 \u0915\u0940 \u0939\u0948\u0964 \u0926\u0936\u092e \u092d\u093e\u0935 \u092e\u0947\u0902 \u0938\u093f\u0902\u0939 \u0930\u093e\u0936\u093f \u092a\u0930 \u092c\u0941\u0927 \u0938\u094d\u0925\u093f\u0924 \u0939\u0948\u0902 \u0914\u0930 \u0938\u0942\u0930\u094d\u092f \u0928\u0935\u092e \u092d\u093e\u0935 \u092e\u0947\u0902 \u0927\u0930\u094d\u092e-\u0915\u0930\u094d\u092e \u0906\u0927\u093f\u092a\u0924\u094d\u092f \u092f\u094b\u0917 \u092c\u0928\u093e \u0930\u0939\u0947 \u0939\u0948\u0902...",
        "chart_summary": {
            "ascendant": "Scorpio",
            "moon_sign": "Pisces",
            "nakshatra": "Revati",
            "running_dasha": "Sun / Jupiter"
        },
        "credits_used": 5,
        "credits_remaining": 49995
    }
}