---
title: "24 Solar Terms"
method: GET
path: "/api/public/solar-terms"
---

# 24 Solar Terms

`GET /api/public/solar-terms`

## Request

- Base URL: `https://totallytarot.net`
- URL: `https://totallytarot.net/api/public/solar-terms`
- Auth: none declared

The 24 solar terms (jieqi) of a year: the instant the Sun's apparent ecliptic longitude crosses each multiple of 15 degrees, in UTC, in Beijing time and, if a zone is given, in that zone, each with its uncertainty band in seconds. Instants come from our own table built from JPL's DE440 and DE441 ephemerides. A year in which any term's band holds a midnight, in Beijing or in the zone asked about, is reported as unverified, because that term's civil date is not established.

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

- `year` string, required
- `tz` 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)