openephemeris-com · Schema
BaZiLuckPillarsRequest
Request for Da Yun (大运) luck pillar calculation. Requires either year/month/day or datetime, plus gender.
CompanyAstrologyArtificial IntelligenceAstronomyData
Properties
| Name | Type | Description |
|---|---|---|
| datetime | string | ISO 8601 alternative to year/month/day/hour. Its calendar components are read as the naive LOCAL wall clock; the UTC offset the string spells is not used to convert them. Because of that, a datetime c |
| day | integer | |
| day_boundary | object | Day-pillar boundary convention. zi_hour (default) rolls the day pillar at 23:00, the start of the Zi hour; midnight rolls it at 00:00. The hour branch is Zi either way — what changes is the day pillar |
| format | string | Response format: json | llm. |
| gender | string | Required: determines direction (forward/backward) of Da Yun progression. |
| hour | integer | |
| latitude | number | Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to f |
| longitude | number | Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to f |
| minute | integer | Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it |
| month | integer | |
| timezone | object | Optional IANA timezone for the birth place (tz database identifier, e.g. Asia/Shanghai). The Li Chun and Jie solar-term crossings the year and month pillars roll on are astronomical instants in UT; wi |
| true_solar_time | boolean | When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation |
| year | integer | Birth year (Gregorian) |
| year_boundary | object | Year-pillar boundary convention. lichun (default) rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year, the lunisolar new-year date. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/openephemeris-com/json-schema/openephemeris-com-ba-zi-luck-pillars-request-schema.json",
"title": "BaZiLuckPillarsRequest",
"description": "Request for Da Yun (大运) luck pillar calculation. Requires either year/month/day or datetime, plus gender.",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/openephemeris-com-chinese-api-openapi.yml#/components/schemas/BaZiLuckPillarsRequest",
"properties": {
"datetime": {
"description": "ISO 8601 alternative to year/month/day/hour. Its calendar components are read as the naive LOCAL wall clock; the UTC offset the string spells is not used to convert them. Because of that, a datetime carrying an offset (Z or +/-HH:MM) together with a timezone (or latitude+longitude, from which a zone is resolved) states the birth zone twice: if the two disagree the request is rejected 422 rather than shifted twice. To use a zone, send year, month, day and hour as the local wall clock alongside timezone. Its MINUTES are also discarded: only the hour is read, so \"1990-02-03T22:30:00\" is computed as 22:00. Send hour and minute alongside year/month/day to express a sub-hour birth time.",
"format": "date-time",
"type": "string"
},
"day": {
"maximum": 31,
"minimum": 1,
"type": "integer"
},
"day_boundary": {
"$ref": "#/$defs/BaZiDayBoundaryEnum",
"default": "zi_hour",
"description": "Day-pillar boundary convention. zi_hour (default) rolls the day pillar at 23:00, the start of the Zi hour; midnight rolls it at 00:00. The hour branch is Zi either way — what changes is the day pillar and, through it, the hour stem (the early/late Zi, 早子/晚子, distinction)."
},
"format": {
"description": "Response format: json | llm.",
"enum": [
"json",
"llm"
],
"type": "string"
},
"gender": {
"description": "Required: determines direction (forward/backward) of Da Yun progression.",
"enum": [
"male",
"female"
],
"type": "string"
},
"hour": {
"default": 12,
"maximum": 23,
"minimum": 0,
"type": "integer"
},
"latitude": {
"description": "Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.",
"format": "double",
"maximum": 90,
"minimum": -90,
"type": "number"
},
"longitude": {
"description": "Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.",
"format": "double",
"maximum": 180,
"minimum": -180,
"type": "number"
},
"minute": {
"default": 0,
"description": "Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it becomes load-bearing under true_solar_time, where the correction of up to ~±45 minutes is added to hour+minute/60 before the block and the 23:00 zi-hour tests are applied, and in the solar-term frame, where it shifts the birth instant by up to 59 minutes and can flip a Li Chun or Jié comparison for a birth within an hour of one.",
"maximum": 59,
"minimum": 0,
"type": "integer"
},
"month": {
"maximum": 12,
"minimum": 1,
"type": "integer"
},
"timezone": {
"$ref": "#/$defs/TimezoneInput",
"description": "Optional IANA timezone for the birth place (tz database identifier, e.g. Asia/Shanghai). The Li Chun and Jie solar-term crossings the year and month pillars roll on are astronomical instants in UT; without a zone the naive birth wall clock is compared against them as though it were already UTC, so a birth within roughly the birthplace's UTC offset of a boundary can land on the wrong side and receive the wrong year or month pillar. Supply this (or latitude+longitude, from which a zone is resolved) and the comparison is made at the true birth instant instead. An explicit timezone always wins over the coordinate lookup - use it for border towns and for Xinjiang, where IANA Asia/Urumqi is UTC+06:00 year-round while published BaZi tables assume the UTC+08 Beijing civil clock. The DAY and HOUR pillars are civil-clock concepts and are never reframed. Which frame produced the answer is reported as year_boundary_frame / month_boundary_frame in the response metadata."
},
"true_solar_time": {
"default": false,
"description": "When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation of time. The correction can move the day - and therefore the day pillar and, through it, the hour stem - as well as the hour branch. The year and month pillars are compared at the true birth INSTANT and are unaffected by the correction, which transforms a clock reading rather than moving the birth. Requires latitude and longitude.",
"type": "boolean"
},
"year": {
"description": "Birth year (Gregorian)",
"type": "integer"
},
"year_boundary": {
"$ref": "#/$defs/BaZiYearBoundaryEnum",
"default": "lichun",
"description": "Year-pillar boundary convention. lichun (default) rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year, the lunisolar new-year date."
}
},
"required": [
"gender"
],
"type": "object",
"$defs": {
"BaZiDayBoundaryEnum": {
"description": "Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.",
"enum": [
"zi_hour",
"midnight"
],
"title": "BaZiDayBoundaryEnum",
"type": "string"
},
"BaZiYearBoundaryEnum": {
"description": "Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.",
"enum": [
"lichun",
"cny"
],
"title": "BaZiYearBoundaryEnum",
"type": "string"
},
"TimezoneInput": {
"additionalProperties": false,
"description": "Timezone input using IANA names or UTC offsets.",
"properties": {
"fold_preference": {
"description": "Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.",
"enum": [
"earlier",
"later"
],
"title": "Fold Preference",
"type": "string"
},
"iana_name": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
}
],
"description": "IANA timezone name",
"title": "Iana Name"
},
"time_standard": {
"description": "How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.",
"enum": [
"auto",
"standard",
"daylight"
],
"title": "Time Standard",
"type": "string"
},
"utc_offset": {
"anyOf": [
{
"type": "number"
}
],
"description": "UTC offset in hours",
"title": "Utc Offset"
}
},
"title": "TimezoneInput",
"type": "object"
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/openephemeris-com-ba-zi-luck-pillars-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.