Developer Documents

Authentication

All API requests must include authorization credentials. AstroKul supports token-based authentication for external API integrations.

Include the custom `X-API-Key` header with your active token to each request:

Alternatively, you can use the standard `Authorization` header:

Global HTTP Status Codes

Code	Status	Description
200	OK	Request was successful. Output body contains calculated details.
400	Bad Request	Mandatory request parameters are missing or formatted incorrectly.
401	Unauthorized	Missing, inactive, or invalid API key.
403	Forbidden	Subscription plan limits exceeded or expired.
429	Too Many Requests	Rate limit exceeded.

1. Create/Retrieve Kundli Chart

Generates full charts (Janam, Chandra, Gochar, Lal Kitab Varsh, Vedic Varsh) and birth panchang data in a single request.

JSON Body Parameters

Key	Type	Required	Description
cust_name	string	Yes	Name of the customer.
gender	string	Yes	"male" or "female".
dob	string	No	Date of birth ("YYYY-MM-DD").
tob	string	No	Time of birth ("HH:MM").
city_id	string	Yes	Birth city (resolved coordinates).
target_year	int	No	Year to generate Varshphal (defaults to current year).

Example Request Payload

{
  "cust_name": "Rajesh Kumar",
  "gender": "male",
  "dob": "1995-10-15",
  "tob": "14:30",
  "city_id": "New Delhi",
  "target_year": 2026,
  "language": "hindi"
}

Example Response Payload

{
  "success": true,
  "message": "Kundli created successfully",
  "customer_id": 105,
  "charts": {
    "janam_kundli_html": "<div class='kundli'><img src='https://api.astrokul.com/kundli_imgs/kundali_janam.jpg' /></div>",
    "janam_kundli_image": "https://api.astrokul.com/kundli_imgs/kundali_janam.jpg",
    "chandra_kundli_image": "https://api.astrokul.com/kundli_imgs/kundali_chandra.jpg"
  },
  "panchang": {
    "tithi": "षष्ठी",
    "nakshatra": "आर्द्रा"
  },
  "assistant_yogas": [
    { "name": "Gaja-Kesari Yoga", "type": "auspicious", "description": "Guru and Chandra in kendra..." }
  ]
}

2. Standalone Panchang

Fetches detailed panchang indices (Tithi, Nakshatra, Yoga, Karana, Sun/Moon rises & sets) for a given date, time, and coordinates.

Query Parameters

Key	Type	Required	Description
dob	string	Yes	Date in "YYYY-MM-DD".
tob	string	No	Time in "HH:MM" (defaults to 12:00 PM).
city_id	string	Yes	Target city name (e.g. "New Delhi").

Example Response

{
  "success": true,
  "panchang": {
    "vaar": "रविवार",
    "tithi": "षष्ठी",
    "nakshatra": "आर्द्रा",
    "sunrise": "06:21:40",
    "sunset": "17:52:12"
  }
}

3. Matchmaking (Milan)

Evaluates marital compatibility between a male and a female profile based on the 36 Ashtakoot gunas.

Example Response

{
  "success": true,
  "match_score": 28.5,
  "total_gunas": 36,
  "guna_breakdown": {
    "varna": { "points": 1, "max": 1 },
    "vashya": { "points": 2, "max": 2 },
    "tara": { "points": 1.5, "max": 3 },
    "yoni": { "points": 4, "max": 4 },
    "maitri": { "points": 5, "max": 5 },
    "gana": { "points": 6, "max": 6 },
    "bhakoot": { "points": 7, "max": 7 },
    "nadi": { "points": 2, "max": 8 }
  },
  "compatibility_status": "Highly Compatible"
}

4. Fetch City Data

Resolves geographic locations, latitudes, longitudes, and database keys for search text matching.

Query Parameters

Key	Type	Required	Description
search	string	Yes	Search query (prefix, minimum 2 characters).

Example Response

[
  {
    "id": "1",
    "country_name": "India",
    "state_name": "DELHI",
    "city_name": "New Delhi",
    "lat": "28.37",
    "lng": "77.12"
  }
]

5. Get Chart Types

Lists all supported Vedic and Lal Kitab divisional and solar return chart types with their query slugs.

Example Response

{
  "success": true,
  "charts": [
    { "slug": "lagan", "name": "Lagan Chart (D1)", "system": "Vedic/Lal Kitab" },
    { "slug": "chandra", "name": "Chandra Chart (Moon)", "system": "Vedic/Lal Kitab" },
    { "slug": "gochar", "name": "Gochar Chart (Transit)", "system": "Vedic" },
    { "slug": "vedic_varsh", "name": "Vedic Varsh Chart (Solar Return)", "system": "Vedic" },
    { "slug": "lalkitab_varsh", "name": "Lal Kitab Varsh Chart", "system": "Lal Kitab" },
    { "slug": "d2", "name": "Hora Chart (D2)", "system": "Vedic" }
  ]
}

6. Get Chart Details

Renders a specific chart's SVG image structure and parses the planet-in-house position arrays.

Query Parameters

Key	Type	Required	Description
kid	int	Yes	The ID of the saved customer profile.
chart_name	string	Yes	Slug of the chart (e.g. "d9", "lagan").

Example Response

{
  "success": true,
  "chart_name": "d9",
  "chart_html": "<div class='kundli'><img src='https://api.astrokul.com/kundli_imgs/kundali_janam.jpg' /></div>",
  "chart_image_url": "https://api.astrokul.com/kundli_imgs/kundali_janam.jpg",
  "placements": [
    { "planet": "लग्‍न", "rashi": 9, "house": 1, "degree": 12, "min": 34 },
    { "planet": "सू", "rashi": 2, "house": 6, "degree": 5, "min": 21 },
    { "planet": "च", "rashi": 5, "house": 9, "degree": 28, "min": 44 }
  ]
}

7. Delete Customer Profile

Deletes an existing customer record, validating ownership permissions and checking the sub-account caller constraints.

JSON Body Parameters

Key	Type	Required	Description
customer_id	int	Yes	The ID of the customer record to delete.
caller_id	string	No	Token context of caller to restrict unpermitted sub-user deletions.

Example Response

{
  "success": true,
  "message": "Customer deleted successfully",
  "customer_id": 42
}

8. Matchmaking PDF Report Export

Generates a beautifully styled, custom-branded Ashtakoot Milan PDF report with compatibility score details and saves it to server files. Restricted to Premium plans (or Free plans during their 7-day grace period).

JSON Body Parameters

Key	Type	Required	Description
user_id	int	Yes	Astrologer user ID requesting the report (to inject branding headers).
boy_name	string	Yes	Male subject name.
boy_dob	string	Yes	Male date of birth ("YYYY-MM-DD").
boy_tob	string	Yes	Male time of birth ("HH:MM").
boy_lat	float	Yes	Male birth place latitude.
boy_lng	float	Yes	Male birth place longitude.
girl_name	string	Yes	Female subject name.
girl_dob	string	Yes	Female date of birth ("YYYY-MM-DD").
girl_tob	string	Yes	Female time of birth ("HH:MM").
girl_lat	float	Yes	Female birth place latitude.
girl_lng	float	Yes	Female birth place longitude.

Example Response

{
  "success": true,
  "filePath": "kundli_pdfs/match_12345.pdf",
  "fileName": "Rohan_&_Priya_Matchmaking.pdf"
}