chinese

Render BaZi Chart (SVG/PNG)

Render the Four Pillars (八字 BaZi) as a finished chart image — the same computation as POST /chinese/bazi, drawn.

Returns the four pillars, the Day Master, the Five-Element (五行 Wu Xing) balance and the Yong Shen (用神, favourable element) as a single self-contained SVG, a base64 PNG, or a bare SVG blob — no client-side charting required.

Output — select with visual_config.format:

  • svg (default): JSON envelope with the SVG string in visual.data.
  • png: JSON envelope with base64 PNG in visual.data.
  • svg-raw: a bare image/svg+xml body, no JSON envelope. Convenient for <img src>, but it carries no calculation_metadata, so the convention echo is unavailable in this mode.

Conventions: accepts the same five convention fields as POST /chinese/bazi (solar-term boundary, hour-pillar rule, zone handling), and echoes what was used in calculation_metadata.

Metering: 3 units per call — 1 for the pillar computation plus 2 for the visual render. credits_used reports the total actually charged.

post/chinese/bazi/chart

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/chinese/bazi/chart
  • Auth: one of:
    • HTTP bearer
    • API key in header X-OpenEphemeris-API-Key
    • API key in header X-API-Key
    • API key in header X-Service-Key

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Request body

datetimestring

ISO 8601 fallback when year/month/day are absent.

dayinteger

Day of month.

day_boundary'zi_hour' | 'midnight'

Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.

format'json' | 'llm'

Response format: json | llm.

hourinteger nullable

Hour 0-23. Omit for a three-pillar chart.

latitudenumber double

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.

longitudenumber double

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.

minuteinteger

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.

monthinteger

Month, 1-12.

true_solar_timeboolean

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.

yearinteger

Gregorian year.

year_boundary'lichun' | 'cny'

Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.

Example request

{
  "latitude": 31.2304,
  "longitude": 121.4737,
  "minute": 30,
  "timezone": {
    "iana_name": "America/New_York"
  }
}

Response

Rendered BaZi chart. svg and png return the JSON envelope; svg-raw returns a bare SVG document.

calculation_metadataobject

Convention echo. Absent for visual_config.format = svg-raw.

credits_usedinteger

Total units charged (3).

dateobject

Echo of the date/time actually used.

day_masterstring

Day Master (日主) label.

visualobject

Rendered artefact: type, format, content_type, data, credits_charged.

Changes

No recorded changes to this operation across all 1 revision of this API.