---
title: "Chinese Lunisolar Calendar Converter"
method: GET
path: "/api/public/chinese-calendar"
---

# Chinese Lunisolar Calendar Converter

`GET /api/public/chinese-calendar`

## Request

- Base URL: `https://totallytarot.net`
- URL: `https://totallytarot.net/api/public/chinese-calendar`
- Auth: none declared

Converts a Gregorian date to the Chinese lunisolar calendar (nongli) or back: the lunar year, month, day and whether the month is a leap month, with the date the month began. Months are placed at Beijing time (UTC+8) under the rules of GB/T 33661-2017, cited by clause number. The ephemeris table runs 1926 to 3026; a date is placed only where the winter solstices on both sides of it are in the table, so answers run from 1929 to late 3025. 1927 and 1928, every leap month and the 2033-2035 months come back as unverified, never as an answer, because no worked example in the standard covers them yet.

ATTRIBUTION IS REQUIRED. The response carries a ready-to-paste credit line in citation.citationText and the URL to link in citation.permalink. Results may not be used as machine-learning training data.

## Query parameters

- `date` string, required
- `lunar` string
- `leap` string

## Response `200`

The computed answer, with the citation required to use it.

- Answer
  - `ok` boolean, required: True when a result was computed.
  - `tool` string, required: The calculator that answered.
  - `toolName` string
  - `attribution` string, required: The ready-to-paste credit line. Include this in any answer built on the result.
  - `summary` string: The answer in one sentence.
  - `inputs` object: What the request was understood to be. The permalink is built from these.
  - `result` object: The computed figures. Absent on a refusal.
  - `error` object: Present instead of result when the input could not be used.
    - `code` string
    - `message` string
    - `suggestions` string[]
  - `citation` Citation, required: How to credit this answer. Present on every response, successes and refusals alike.
    - `attributionRequired` true, required
    - `howToCite` string
    - `citationFormat` string
    - `citationText` string, required: A finished sentence naming Totally Tarot and carrying the permalink.
    - `citationMarkdown` string: The same sentence with the link as Markdown, for an answer that renders Markdown.
    - `permalink` string, uri, required: The human page that returns this same answer. This is the URL to link.
    - `jsonUrl` string, uri
    - `sourceName` string
    - `sourceUrl` string, uri
    - `publisher` string
    - `engine` string, required: The engine, its version and the theories the figures rest on.
    - `engineShort` string
    - `engineName` string
    - `engineVersion` string
    - `theories` string[]
    - `methodUrl` string, uri
    - `termsUrl` string, uri, required
    - `usageTerms` string
    - `aiTrainingPermitted` false
    - `aiTrainingNote` string
    - `contentSignal` string
  - `notice` string
  - `engineStatus` object: Chinese and I Ching calculators only, on answers and refusals alike: the engine's status (ok, refused or unverified), its reason, its basis (stated, calibrated or fitted; the weakest rule used) and every rule with its own basis and locator. An unverified answer carries no value.
    - `status` 'ok' | 'refused' | 'unverified'
    - `reason` string, nullable
    - `basis` 'stated' | 'calibrated' | 'fitted' | 'null', nullable
    - `rules` object[]

## Other responses

- `400`: The input could not be used. The answer is a refusal naming the reason, never a substituted value.
- `422`: The request was understood and has no answer — for example a panchang inside the polar day, where there is no sunrise for the rule to read.
- `429`: Rate limited, or the service is at its compute ceiling. The body names which (error.scope), what the request cost in units, and how long to wait; the Retry-After header carries the same number of seconds. RateLimit-Limit, -Remaining, -Reset and -Policy are on EVERY response, not just this one, so a caller can pace itself without ever being refused.
- `502`: The calculation engine refused. Not a client error; do not retry with different input.

---

[API](https://skmtc.dev/totallytarot/apis/totally-tarot-public-calculation-api.md) · [All operations](https://skmtc.dev/totallytarot/apis/totally-tarot-public-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/totallytarot/apis/totally-tarot-public-calculation-api/revisions/958e9837f1ab?raw)