API reference

Chinese astrology

Chinese zodiac, the Four Pillars and yearly forecasts.

2 endpoints
POST JSON body
Bearer key

2 endpoints. Every endpoint is POST with a JSON body and your key in the Authorization header. Request schemas and examples come from the OpenAPI document; each example response was captured from the live engine, and each endpoint says where its data fields come from: a hand-written contract, a schema measured from several real answers, or the one example.

Chinese Zodiac and Four Pillars

POSTAvailable

POSThttps://api.96astroapi.com/v1/chinese/chinese-chart

Zodiac animal by the lunar new year, year, month, day and hour pillars, day master, compatible animals and clash.

Credits: 1 credit
Input: Birth details
Output: JSON
Delivery: Direct response
Languages: English; translated term names with labels

Headers
Header	Value and description
`Authorization`Required	`Bearer YOUR_API_KEY` Your sandbox (sk_test_...) or live (sk_live_...) key. X-API-Key: <key> is accepted instead.
`Content-Type`Required	`application/json` The body is JSON.
`Idempotency-Key`Optional	`<unique string>` Makes retries safe: a repeated key with the same body replays the stored response and is never charged twice. (1 to 200 characters)

Body · application/json
Field	Description
`datetime`stringRequired	Local date and time, ISO 8601 without offset, e.g. 1990-10-18T14:30:00 Limits: format local-date-time, pattern ^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?$ Example: `1990-10-18T14:30:00`
`timezone`string \| nullOptional	IANA time zone, e.g. Asia/Kolkata Default: `null` Example: `Asia/Kolkata`
`utc_offset`string \| nullOptional	Fixed offset such as +05:30, if no IANA zone is known Default: `null` Limits: pattern ^[+-]?\d{1,2}(:[0-5]\d)?$ Example: `+05:30`
`latitude`numberRequired	Latitude in decimal degrees, north positive, e.g. 28.6139. Limits: minimum -90, maximum 90 Example: `28.6139`
`longitude`numberRequired	Longitude in decimal degrees, east positive, e.g. 77.209. Limits: minimum -180, maximum 180 Example: `77.209`
`ayanamsha`stringOptional	Sidereal system for Vedic positions. Default lahiri. `ayanamsha-list` compares seven of them. Default: `lahiri`
`language`stringOptional	Output language (ISO 639-1). The values listed are the ones this capability supports; any other is refused with 422 unsupported_language. Identifiers, enum values and numbers never change with language. Default: `en` Allowed value: en
`labels`stringOptional	Optional. Adds `meta.labels`: translated display names for the identifiers in the answer. `data` is unchanged. Free. Any other code is refused with 422 unsupported_language. Allowed values: asbndeesfrguhiitknkomlmrnenlorpaplptrusitatetrur

Response · fields in data

Measured from 6 real answers to different inputs: a required field was in every one.

lunar_year · number
new_year_date · string
zodiac_animal · string
element · string
polarity · string
traits · string
pillars · object
day_master · object
compatible_animals · array of string
clash_animal · string

Try in Playground →Capability overview

Example request

curl -X POST https://api.96astroapi.com/v1/chinese/chinese-chart \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "datetime": "1990-10-18T14:30:00",
  "timezone": "Asia/Kolkata",
  "latitude": 28.6139,
  "longitude": 77.209
}'

const response = await fetch("https://api.96astroapi.com/v1/chinese/chinese-chart", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "datetime": "1990-10-18T14:30:00",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209
  }),
});

const { data, meta } = await response.json();
console.log(data);

import { Astro96Client } from "@96astro/api";

const astro = new Astro96Client({ apiKey: "YOUR_API_KEY" });

const { data, meta } = await astro.chinese.chineseChart({
  "datetime": "1990-10-18T14:30:00",
  "timezone": "Asia/Kolkata",
  "latitude": 28.6139,
  "longitude": 77.209
});
console.log(data);

import requests

response = requests.post(
    "https://api.96astroapi.com/v1/chinese/chinese-chart",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "datetime": "1990-10-18T14:30:00",
        "timezone": "Asia/Kolkata",
        "latitude": 28.6139,
        "longitude": 77.209,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()["data"]
print(data)

from astro96_api import Astro96Client

astro = Astro96Client(api_key="YOUR_API_KEY")

res = astro.chinese.chinese_chart({
    "datetime": "1990-10-18T14:30:00",
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139,
    "longitude": 77.209,
})
print(res.data)

<?php
$ch = curl_init('https://api.96astroapi.com/v1/chinese/chinese-chart');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'datetime' => '1990-10-18T14:30:00',
        'timezone' => 'Asia/Kolkata',
        'latitude' => 28.6139,
        'longitude' => 77.209,
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result['data']);

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "datetime": "1990-10-18T14:30:00",
  "timezone": "Asia/Kolkata",
  "latitude": 28.6139,
  "longitude": 77.209
}`)
	req, err := http.NewRequest("POST", "https://api.96astroapi.com/v1/chinese/chinese-chart", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

Example response

200application/json

{
  "data": {
    "lunar_year": 1990,
    "new_year_date": "1990-01-27",
    "zodiac_animal": "Horse",
    "element": "Metal",
    "polarity": "Yang",
    "traits": "energetic and independent",
    "pillars": {
      "year": {
        "stem": "Geng",
        "branch": "Wu",
        "animal": "Horse",
        "element": "Metal",
        "polarity": "Yang"
      },
      "month": {
        "stem": "Bing",
        "branch": "Xu",
        "animal": "Dog",
  …

Captured from the live engine with a sandbox key (so credits_used is 0) and trimmed: long arrays keep their first items.

Error responses

400invalid_request
401invalid_key, expired_key
402payment_required
403account_suspended, plan_upgrade_required, plan_family_not_included, key_scope_denied, ip_not_allowed, origin_not_allowed, publishable_key_not_allowed
404not_found
409idempotency_conflict
413payload_too_large
422invalid_request, unsupported_language
429rate_limited, quota_exhausted, spend_cap_reached, project_budget_exceeded
500computation_failed
502unavailable
503unavailable, maintenance, temporarily_unavailable
504deadline_exceeded

Errors are never charged. What each status means and what to do: errors.

Chinese Year Forecast