Horoscope Learning Guide

What is a Horoscope API?

A Horoscope API turns a person’s birth date, time, and place into a structured Vedic birth chart (Kundli) as JSON, so applications can build astrology experiences without maintaining their own astronomical engine.

For developers and product teams Kundli API Updated July 8, 2026

The Short Version

The DevDarsha Horoscope API converts birth input into developer-friendly JSON. The core object is the Kundli — a Vedic sidereal birth chart with planetary positions, houses, and signs. Protected calls are authenticated with an API key and use URI versioning under /v1/....

The /v1/horoscope/kundli endpoint is the free-tier entry point and the best place to start: it exercises birth input, city resolution, calculation conventions, and the response envelope in a single call.

What this guide is for

This is a learning guide, not the API reference. Use it to understand the request and response shape, then use Documentation for exact fields, schemas, errors, and examples.

Birth Input

Birth-based endpoints take a small JSON body. The API accepts a city name and resolves its coordinates and timezone for you, so you do not need to send latitude and longitude:

{
  "date": "1990-08-15",
  "time": "10:30",
  "city": "Kolkata"
}

Throughout the Horoscope guides, examples use a single sample birth — Aarav Sharma, born 1990-08-15 at 10:30 in Kolkata. Swap the details to match your use case.

How to Call the Kundli Endpoint

Keep your API key on the server and send it in the x-api-key header. A minimal request looks like this:

curl -X POST https://horoscope.devdarsha.com/v1/kundli \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"date":"1990-08-15","time":"10:30","city":"Kolkata"}'

Birth-based endpoints use POST. Public read-only endpoints such as rashifal, health, and status use GET.

Response Envelope

Responses use a consistent envelope with data, meta, and dev_notes. The data object holds the chart payload. The meta object explains how the response was produced:

  • meta.calculation.zodiac: the zodiac model, "sidereal".
  • meta.calculation.ayanamsa: the active ayanamsa, for example "Lahiri (Chitrapaksha)".
  • meta.calculation.house_system: the house system, for example "whole-sign".
  • meta.version and meta.computed_at: the API version and computation time.

Useful headers include X-Request-ID and X-Quota-Cost. Store the request ID when debugging a production issue.

Versioning and Stability

The public API uses URI versioning, so routes look like /v1/kundli and /v1/rashifal/:sign/:period. The surface may expand over time; retired versions are expected to receive notice, and deprecated responses can include migration guidance in dev_notes.

Recommended Developer Flow

Start with the free-tier Kundli endpoint or Playground to inspect a real chart. Once the shape is clear, decide whether your product also needs divisional charts, dashas, doshas, matching, or rashifal. Test representative births and make sure your UI handles optional or plan-gated fields gracefully before launch.

Back to Guides Open Documentation View Pricing Try Playground