Requests and responses
Dates, time zones, places, languages, options and the response envelope.
Base URL and format
https://api.96astro.com/v1Requests are POST with a JSON body (Content-Type: application/json). Capability responses are always JSON. A few chart capabilities include SVG drawings as strings inside the JSON, and their reference entry says so. PDFs are made by report jobs.
Date and time
Send the local date and time as ISO 8601 without an offset, plus an IANA time-zone name:
{ "datetime": "1990-10-18T14:30:00", "timezone": "Asia/Kolkata" }We resolve the offset for that exact date, including historical changes and daylight saving. If a local time is ambiguous (clocks went back) or does not exist (clocks went forward), you get 422 ambiguous_local_time listing the valid choices; we never guess.
If you only have a fixed offset, send "utc_offset": "+05:30" instead of timezone.
Place
latitude and longitude are decimal degrees: north and east positive, south and west negative. To find coordinates and the time zone for a place name, use the place-search capability under Utilities.
Astrology settings
| Field | Default | Notes |
|---|---|---|
ayanamsha | lahiri | Sidereal capabilities. The reference lists every supported value. KP capabilities always use the Krishnamurti ayanamsha |
house_system | per capability | Western capabilities take P Placidus (the default), K Koch, W whole sign or E equal. KP capabilities always use Placidus cusps. The OpenAPI document lists each capability's values |
node | true | true (osculating) or mean lunar node, on chart capabilities |
An unsupported value is rejected with 422. The API never silently substitutes a default. Responses echo the settings used where they apply, for example ayanamsha, node and house_system in planet positions.
Language
Each capability lists the languages it answers in: the language enum of its request and x-languages in the OpenAPI document. Today 4 capabilities, the AI readings, answer in 26 languages, and every calculation and report answers in English. Any request can add labels for translated display names of the terms in the answer (13 Indian languages and more): see the languages page. The languages page has the table by family.
AI readings take these ISO 639-1 codes:
as bn de en es fr gu hi it ja kn ko ml mr ne nl or pa pl pt ru si ta te tr ur
An AI reading is written by a language model in the language you ask for; the text is machine-written and has not been reviewed by native speakers. A language a capability does not support is rejected with 422 unsupported_language, and the error's supported lists the ones it takes. en (the default) is accepted everywhere.
Field names, IDs, enum values and numbers never change with language; only display text does. meta.language states the language the answer is in.
Response envelope
Every successful response has the same shape:
{
"data": { },
"meta": {
"request_id": "req_6e985a89a166b73ea220",
"api_version": "v1",
"credits_used": 3,
"warnings": [],
"language": "en"
}
}- Lists are arrays. Planets, houses and periods are arrays of objects with named fields, never objects keyed
"0","1". - Missing versus empty.
[]means the calculation ran and found nothing;nullmeans a value does not apply, with the reason inmeta.warnings. - Dates in responses are ISO 8601 with an explicit offset.
request_ididentifies the call (req_and 20 hex characters). It is also in theX-Request-Idheader of every response, including errors; quote it when you contact support.