Unified Reading.
← Unified Reading

For developers

Unified Reading API

Unified Reading has a small public API for the calculations that need only a birth date: the Life Path number, the Western Sun sign and the Chinese zodiac animal, plus the Lunar New Year table behind the Chinese zodiac. It is read-only, needs no API key and stores nothing. The combined personal reading is only available through the website form, where the person enters their own details.

SDK and CLI

The unified-reading npm package wraps every endpoint, with TypeScript types and no dependencies (source).

npx unified-reading profile 1990-07-14

import { UnifiedReading } from "unified-reading";
const profile = await new UnifiedReading().profile("1990-07-14");

GET /api/v1/profile

Query parameter date (required): the birth date as YYYY-MM-DD, from 1900 up to today. Send only the date, never a name, birth time or place.

curl "https://unifiedreading.com/api/v1/profile?date=1990-07-14"

The response has lifePath (number, title, brief, keywords), sunSign (sign, decan, element, modality, ruling planet) and chineseZodiac (animal, element, yin-yang, best matches), each with a link to its library guide. Master numbers 11, 22 and 33 are kept. The Chinese animal follows the Lunar New Year date, not January 1. The Sun sign assumes midday, so a birth on a sign change day may fall in the neighbouring sign. Try it.

POST /api/v1/profiles/batch

The same profile for up to 20 dates in one call, in request order. An invalid date fails only its own item.

curl -X POST "https://unifiedreading.com/api/v1/profiles/batch" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a4e-9d1b-4c55-8a0e-1d2f3b4c5d6e" \
  -d '{"dates": ["1990-07-14", "1990-01-20"]}'

Each item is { date, ok: true, profile } or { date, ok: false, error }. The calculation has no side effects, so retrying is always safe. An optional Idempotency-Key header is validated and echoed back, so a client can match a retry to its first attempt.

GET /api/v1/chinese-zodiac/years

Every zodiac year from 1924 to 2044 with its animal, stem element, yin-yang, and the dates it starts (Lunar New Year) and ends.

curl "https://unifiedreading.com/api/v1/chinese-zodiac/years?limit=12"

Pages hold 12 years by default (limit 1-60). Pass next_cursor back as cursor, or follow the Link: rel="next" header, until has_more is false.

Rate limits

All endpoints share 10 requests per minute per IP. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers; a 429 adds Retry-After.

Errors

Every error is JSON with a stable code, a message and a hint:

{ "error": { "code": "invalid_date", "message": "date must be a real YYYY-MM-DD date from 1900 up to today.", "hint": "Use a zero-padded calendar date such as 1990-07-14.", "status": 400, "docs": "https://unifiedreading.com/docs" } }

Versioning and testing

The version is in the path (/api/v1) and the X-API-Version header. Fields may be added within v1; a breaking change gets a new path, and v1 keeps working for at least 90 days after a replacement is announced in the repository. There is no separate sandbox: the API is free, read-only and has no side effects, so test against production with a fictional date.