True solar time

POST

/chinese/true-solar-time

request.sh

curl -X POST https://api.astroway.info/v1/chinese/true-solar-time \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "date": "1995-06-15", "time": "09:20:00", "timezoneOffset": 8, "longitude": 75.9 }'

▸ Спробувати POST /chinese/true-solar-time

• Production

The clock corrected to the sun over the birth longitude, split into the meridian term and the equation of time. China runs one zone across sixty degrees, so a Kashgar birth reads nearly three hours from solar noon on a Beijing clock, which moves the hour pillar.

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

fields

string

Comma-separated dotted paths, relative to data, to keep in the response. A path is applied to every element of an array, so planets.name means the name of each planet. Paths that match nothing come back in _fields_unmatched; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer.

Example

planets.name,planets.longitude

precision

integer

<= 15

Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute.

Example

4

Request Body ^required

Media type application/json

object

date required

string

/^\d{4}-\d{2}-\d{2}$/

time required

string

/^\d{2}:\d{2}(:\d{2})?$/

timezoneOffset required

Ignored when timezone is sent.

number

>= -14 <= 14

timezone

IANA zone name such as Europe/Kyiv, or auto to look the zone up from latitude and longitude. The server takes the offset that zone kept at this local date and time, summer time included, and uses it in place of timezoneOffset. A clock time that happened twice takes the first occurrence; one skipped when clocks went forward takes the offset from before the change. Abbreviations such as EST are refused. Before 1970 the tz database is not reliable for every place, so send timezoneOffset when the local clock is known.

string

longitude required

number

>= -180 <= 180

language

string

Example

{
  "date": "1995-06-15",
  "time": "09:20:00",
  "timezoneOffset": 8,
  "longitude": 75.9
}

Responses

200

Successful calculation

Media type application/json

object

ok

boolean

data

object

input

object

date

string

nullable

time

string

nullable

timezoneOffset

number

nullable

longitude

number

nullable

clockTime

string

nullable

trueSolarTime

string

nullable

totalCorrectionMinutes

number

nullable

longitudeCorrectionMinutes

number

nullable

equationOfTimeMinutes

number

nullable

dayShift

number

nullable

date

string

nullable

hourBranchNote

string

nullable

methodology

string

nullable

note

string

nullable

source

string

nullable

Example

{
  "ok": true,
  "data": {
    "input": {
      "date": "1995-06-15",
      "time": "09:20:00",
      "timezoneOffset": 8,
      "longitude": 75.9
    },
    "clockTime": "09:20:00",
    "trueSolarTime": "06:23:20",
    "totalCorrectionMinutes": -176.66,
    "longitudeCorrectionMinutes": -176.4,
    "equationOfTimeMinutes": -0.26,
    "dayShift": 0,
    "date": "1995-06-15",
    "hourBranchNote": "The double-hour is cut from the sun over the birth place, so this is the clock the hour pillar should be read from. A correction of an hour or more moves the branch; near midnight it moves the day pillar too.",
    "methodology": "True solar time is the hour angle of the apparent Sun at the birth longitude, carried round by half a day. It decomposes into the meridian term, (longitude - 15 x timezoneOffset) x 4 minutes, and the equation of time, the Sun's own annual wobble of up to about sixteen minutes. Both are reported.",
    "note": "timezoneOffset is the offset the clock was actually running on, which only the caller knows: a 1988 Beijing birth ran on UTC+9 under summer time, not UTC+8, and no arithmetic here can recover that from the date.",
    "source": "Swiss Ephemeris apparent right ascension; equation of time verified against the published annual extrema"
  }
}

400

Validation error

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Date must be YYYY-MM-DD",
    "details": [
      {
        "path": "date",
        "message": "Date must be YYYY-MM-DD"
      }
    ]
  }
}

401

Missing or invalid API key

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}