BaZi (Chinese Four Pillars) day pillar and Day Master were wrong on every request the API has ever served — an off-by-eight anchor error caught while adding the timezone/`true_solar_time` conventions users had asked for. Both are fixed, both are gated by a new golden suite sourced from HKO, NAOJ, JPL Horizons, Espenak, Aslaksen, ytliu0 and Academia Sinica, and MCP tools now expose the fix.
＋Added
- BaZi requests can now carry `timezone` (or `latitude`/`longitude`, from which a zone is resolved) so the Li Chun and Jié solar-term crossings that roll the year and month pillars are compared against the true birth instant instead of the naive local clock — a birth within roughly the birthplace's UTC offset of a boundary could otherwise land on the wrong side and get the wrong pillar. An explicit `timezone` always wins over the coordinate lookup, which matters for Xinjiang: IANA `Asia/Urumqi` is UTC+06:00 year-round, while published BaZi tables assume the UTC+08 Beijing civil clock.
- `minute` (0-59) is now accepted alongside `hour` on every BaZi endpoint. It only moves the answer under `true_solar_time` or within an hour of a solar-term boundary, but in those cases it can flip a pillar.
- Every BaZi response now echoes `calculation_metadata`, stating which `year_boundary`, `day_boundary` and timezone frame actually produced the pillars, so a chart no longer has to be reverse-engineered to know which convention it used.
- MCP: `chinese_bazi`, `bazi_ten_gods`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_chart`, `explore_bazi_chart` and `bazi_compatibility` (per chart, as `chart_a_*`/`chart_b_*`) all gained `minute`, `year_boundary`, `day_boundary`, `true_solar_time` and `latitude`/`longitude`, and now forward `timezone` to the API instead of using it only to parse a zoned `datetime` locally.
△Improved
- A BaZi golden fixture now gates every pillar calculation against externally-sourced reference data — Hong Kong Observatory, the National Astronomical Observatory of Japan, JPL Horizons, Fred Espenak's solar-term tables, Helmer Aslaksen's published examples, ytliu0's calendar conversion tables, and Academia Sinica's Chinese-Western calendar concordance — instead of only testing the implementation against itself.
⬡Fixed
- The BaZi day-pillar anchor was wrong on every request the API has ever served. Julian Day 2451559 (2000-01-07) is Ren-Shen in the sexagenary cycle, not Jia-Zi — the anchor the day-pillar calculation rolled from. Because the hour pillar's stem and the Day Master both key off the day stem, this was wrong on 2 of the 4 pillars on every BaZi chart, and every Ten God relation, element-balance score and compatibility score computed from it.
- The month pillar was wrong for autumn and early-winter births, roughly 8 October through 5 January. The solar-term seeding for the three Jié past 180° of solar longitude (Hanlu at 195°, Lidong at 225°, Daxue at 255°) landed in the previous calendar year instead of the current one.
- A shared root-cause fix in the solar-term crossing search corrects solar-term, cross-quarter and moon-phase timing across the API, not just in BaZi.
A leaner MCP tool surface — 32 tools advertised by default instead of 69, which roughly halves the context a session spends before you have asked anything, without removing a single capability. Every datetime in the API now carries its own `timezone`, and a datetime that gives a clock time without saying which zone it is in is now rejected rather than assumed to be UTC.
＋Added
- MCP: a focused default tool list, with the full catalog one flag away. `tools/list` now returns a curated core — 32 tools over HTTP, 35 over stdio — instead of all 69: one interactive app per tradition, the main data tool per domain, geocoding, account usage, and the allowlist-gated generic proxy. That takes the tool definitions from about 27,800 tokens to about 15,100, so a conversation starts with room to actually work. Nothing was taken away. This filters what gets listed, not what exists: all 91 registered tools remain callable by name, and a regression test holds that line. Want everything? `OPENEPHEMERIS_TOOLS=full` on stdio, or `?profile=full` / `X-OE-Tool-Surface: full` on remote HTTP. The surface is set when the session initializes, so switching means reconnecting.
- Every datetime now takes its own zone. `date_time`, `birth_datetime`, `target_datetime` and `transit_datetime` all accept a `timezone`, so you can send the local wall-clock time and name the zone rather than doing the UTC conversion yourself: `{"date_time": {"iso": "1987-07-15T09:01:00", "timezone": {"iana_name": "America/Chicago"}}}`. Until now the zone could only ride along on a subject's birth location, which left the nine endpoints built around a bare `date_time` — `/ephemeris/angles-points`, `/ephemeris/house-cusps`, `/ephemeris/planet-position`, `/ephemeris/dignities`, `/ephemeris/midpoints`, `/ephemeris/retrograde-status`, `/ephemeris/fixed-stars`, `/ephemeris/hermetic-lots`, `/ephemeris/lunar-phase` — with nowhere to put one. This is purely additive: leave `timezone` out and nothing changes, and a zone already written on the string still wins, so adding one can never move an instant you had already pinned. Reach for `iana_name` over `utc_offset` — an IANA zone gets DST right for the date in question, where a fixed offset is only right for part of the year.
- MCP: every tool that takes a datetime now takes a `timezone`, up from four. `ephemeris_synastry`, `ephemeris_relocation`, the return tools, the ACG tools, `ephemeris_angles_points`, `ephemeris_house_cusps` and the rest can now express a local birth time directly. A test fails the build if a new tool gains a datetime parameter without one.
- `account_usage` — a free tool that answers "how many credits do I have left?" without leaving the chat: plan tier, billing period, credits used, included and remaining, total calls, and subscription status with renewal date. Pass a `month` (YYYY-MM) to look at an earlier period.
- `location_search` and `timezone_resolve` are now visible to the model. Both existed but were app-only, so turning a birth city into coordinates and an IANA zone meant routing through the generic API proxy. It is a first-class two-step now.
- Responses tell you which moment they used. Every datetime-resolving endpoint echoes `resolved_utc`, the zone as you stated it (`datetime_zone`), and how that zone was established (`datetime_zone_source` — `offset`, `timezone`, `date_only`, `julian_day` or `utc`). Checking what a chart was cast for no longer means working backwards from the output.
△Improved
- The datetime rules are written down, and stated where you actually read them. The `iso`, `components` and `timezone` fields, the plain-string date fields, and the OpenAPI Supported Formats section all now say what they require — see [the API reference](/docs). The rule is short: if a value gives a clock time, it has to say which zone that clock is in, either with a `Z`/`±HH:MM` suffix or with a `timezone` beside it. A date on its own has no clock to be ambiguous about and still resolves to 12:00 UTC. A `*_utc` field says its zone in its name. `julian_day` is always UTC-based.
- Ten tool descriptions now quote the credit cost that is actually charged. Billing is metered server-side on the URL path and was always right, but the descriptions a model plans from were not, so estimates built on them came out wrong. Corrected: the BaZi analytical tools (1 → 3, and `bazi_compatibility` 2 → 3), the electional tools (2 → 5, and `electional_station_tracker` 3 → 5), and the Venus tools, which claimed 2 and actually cost 1. `ephemeris_retrograde_status` now says plainly that sweeping every planet fans out to ten backend calls and costs 10.
- MCP usage reporting now covers stdio as well as remote HTTP, and records which client is connecting — npm-installed sessions were previously invisible next to hosted ones. It is disclosed and easy to turn off: tool name, duration, error status, client name and a one-way hash of your API key are sent; your key, birth data, coordinates, tool arguments and results are not. `OPENEPHEMERIS_TELEMETRY=0` or `DO_NOT_TRACK=1` disables it.
⬡Fixed
- `/chinese/bazi/chart` charged 4 credits while documenting 3. The route sits behind usage-tracking middleware that had already taken the base credit, and the handler then reserved base plus visual render on top, so every rendered BaZi chart paid its base credit twice. The handler now reserves only the visual surcharge. The cost is 3, as documented.
- `ephemeris_planet_position` described `11` as the South Node. It is not: `10` is the North Node (Mean) and `11` is the North Node (True), and there is no South Node id at all. The description now gives the real ids and points out that the South Node is simply the North Node opposed — add 180°, mod 360.
- Progressed-chart recalculation in the chart-wheel app posted to `/predictive/progressed`, which does not exist. The real path is `/ephemeris/progressed`.
- `ephemeris_natal_transits` declared a `transit_timezone` parameter that the handler never read; it is applied now. And `vedic_chart_recalculate` was dropping the `timezone` that `explore_vedic_chart` accepts, so recalculating from the iframe could hand back a different chart than the one on screen.
- BaZi pillars no longer depend on the timezone of the machine the server happens to be running on. The components are read from the datetime string itself rather than through a `Date` parsed in the host process's local zone, which could shift the hour pillar — and, close to midnight, the day pillar with it.
- `ephemeris_lunar_return` and `ephemeris_planetary_return` advertised an output schema promising an image that neither tool can produce. Both now declare the JSON they actually return.
- WCAG AA contrast is restored in the dark widget palette across the bodygraph, moon-phase, transit-timeline, vedic-chart and BaZi apps. The visual gate now checks both palettes for every app and state — it had only ever rendered one, which is how a whole-palette regression slipped through it.
▽Deprecated
- A datetime that gives a clock time without naming its zone is no longer read as UTC. It now returns HTTP 400 with an RFC 7807 problem of type `https://api.openephemeris.com/problems/ambiguous_datetime`, and the `detail` rewrites the value you sent into each fix that field actually supports. Migrating is a one-line edit either way: put a `Z`/`±HH:MM` offset on the value, or keep the local time and name its zone in the `timezone` field described above. Dates without a clock time are unaffected. If you are on `@openephemeris/mcp-server` 4.0.0 or later there is nothing to change — the tools resolve the zone before the request is sent.
The mandala bodygraph layout and house rings (v3.14.0) are now reachable without writing a request — a Mandala view toggle and a metered house-rings checkbox in the Human Design Bodygraph Explorer, the interactive chart Claude renders for explore_human_design.
＋Added
- MCP: the Human Design Bodygraph Explorer (rendered by `explore_human_design` in MCP Apps hosts, including Claude Desktop) gained a Mandala view toggle in its action bar — switches between the classic bodygraph and the concentric-rings mandala without a new API call, using a hexagram-free ring set for full keyboard and hover support.
- The mandala toggle carries its own "Add house rings" checkbox, location-gated and priced up front (+1 credit, charged only when the ring renders) — off by default even with the mandala on.
⬡Fixed
- The decorative I Ching hexagram ring in the mandala no longer mislabels as an "Inactive gate" on hover, and roughly halves the number of keyboard tab stops on the chart.
The bodygraph can now be rendered as a full mandala — I Ching wheel, zodiac, and twin astrological house rings computed from real cusps — on a single query parameter. Plus a fix that unbreaks every PNG render.
＋Added
- New `layout=mandala` on `POST /visualization/bodygraph`: wraps the classic bodygraph in concentric rings — the 16 Godheads, the 64 I Ching hexagrams drawn line by line, the four Quarters, the element-tinted zodiac with a degree scale, and Design/Personality planet lanes at true ecliptic longitude. Each ring is opt-in via a `rings` list (`godhead,quarter,hexagrams,zodiac,planets`); the centered bodygraph auto-fits whatever space the enabled rings leave.
- Twin house rings on the mandala via `rings=...,houses` plus a birth `latitude`/`longitude`: a Personality house ring at the birth moment and a Design house ring at the design moment (~88° of solar arc earlier), each drawn from real unequal cusps with its own AC/IC/DC/MC angles — because the two moments have two different Ascendants. Choose the system with `house_system` (Placidus through Whole Sign). Location-gated (silently omitted without lat/lon) and metered at +1 credit, charged only when the ring renders.
△Improved
- High-latitude house handling now matches the Swiss Ephemeris convention. Quadrant systems (Placidus, Koch, Regiomontanus, Campanus) fall back to Porphyry at the true polar circle (|lat| ≥ 90 − obliquity, ~66.56°) rather than a rounded 66°, so charts in that thin band now render the quadrant system that is still well-defined there.
- `POST /ephemeris/house-cusps` now reports a high-latitude fallback instead of hiding it: when a requested quadrant system is substituted with Porphyry inside the polar circle, the response carries `substituted`, `effective_system_code`, `effective_system_name`, and `substitution_reason` rather than silently mislabeling the output.
⬡Fixed
- PNG rendering (`format=png`) was failing for every bodygraph and chart-wheel render with a `Permission denied` error from the SVG rasterizer, which was told to write its output to a file named "-" instead of to standard output. All `format=png` renders now work again.
- `style=mono` on the bodygraph was silently rendering the dark theme. It now renders a genuine single-hue achromatic theme, and the light theme gained the per-center Human Design color identity it was missing.
Human Design gains two premium overlays: a personalized transit-chart (natal + transiting field, showing the channels a transit temporarily completes) and real connection (synastry) scoring on the composite endpoint. Both are Developer-tier.
＋Added
- New `POST /human-design/transit-chart`: overlays a transiting moment on a natal bodygraph and reports the channels the transit temporarily completes plus any newly-defined centers. Set `include_visual=true` for an overlay bodygraph SVG/PNG. Pro tier.
- MCP tools `explore_human_design_transit` and `explore_human_design_connection` render interactive overlay bodygraphs (transit and two-person connection) in MCP Apps hosts.
△Improved
- `POST /human-design/composite` now returns real connection-channel scoring — every connected channel typed electromagnetic / companionship / dominance / compromise, with combined-center definition and an optional two-person overlay bodygraph. It previously returned an empty result flagged "not yet enabled".
▽Deprecated
- `POST /human-design/composite` moved from Explorer (free) to Pro tier and now costs 3 credits (5 with a visual), matching the comparative relationship endpoints. Free-tier keys that called the previously-stubbed endpoint now receive HTTP 403 `tier_upgrade_required`.
Astrocartography gains an angle-epoch overlay frame, opt-in Human Design gate enrichment, and power-line geometry straight from CCG; geocoding autocomplete gains locale/region bias; ACG crossings now carry structured aspect data.
＋Added
- ACG `angle_epoch` overlay frame: relocated angle lines can be computed against a chosen epoch rather than the natal moment, so epoch-sensitive frames — most notably the Human Design Design line — resolve against the correct time base. (OE-BUG-2026-007)
- Opt-in Human Design gate enrichment on every ACG line type: line and crossing responses can now carry the HD gate and line each activation falls in.
- `include_lines` on `/acg/ccg`: a single call now returns the underlying power-line geometry alongside the CCG crossings, instead of requiring a second request to reconstruct the lines.
△Improved
- Geocoding `/location/autocomplete` now accepts country / region / admin1 / near bias and returns readable region names (e.g. "Springfield, IL"), so birth-data and relocation lookups resolve to the intended place far more often. (OE-BUG-2026-009)
- ACG crossing responses now carry structured `aspect_type` and `angle_type` fields and propagate full aspect data onto each crossing, so clients no longer parse a combined string to know what a crossing is. (OE-BUG-2026-013)
Precomputed-positions rendering for bi-wheel and chart-wheel, per-planet condition on natal & relocation, broader LLM-format coverage, and cleaner JSON output.
＋Added
- Precomputed positions for /visualization/bi-wheel and /visualization/chart-wheel: each subject may supply a `positions` array (plus optional `houses`) instead of birth params, rendering any chart — solar arc directions, progressed/transit hybrids, or parity-exact rings — directly from supplied longitudes. Mixed mode (one ring cast from birth data, the other from positions) is supported, and the emitted SVG/PNG data-attributes are identical to the birth-cast path.
- Per-planet condition data now surfaced on natal and relocation chart responses.
- `no_logo` query parameter on wheel renders suppresses the OpenEphemeris watermark for white-label embeds.
△Improved
- Expanded `?format=llm` token-optimized output to BaZi, Vedic, and predictive returns.
- Optional fields that are unset are now omitted from responses rather than serialized as `null`, for cleaner JSON across the API. (Clients should treat an absent field and a `null` field identically.)
⬡Fixed
- CCG snapshot bodies now include `speed_deg_day` and `is_retrograde`, so retrograde glyphs render correctly in positions-based CCG hybrid wheels.
- The Sun is no longer ever flagged out-of-bounds in per-planet condition.
Major expansion adding Vedic (Jyotish), BaZi (Four Pillars), and Advanced Parans to the API, alongside comprehensive BiWheel comparison modes.
＋Added
- Vedic (Jyotish) API surface: Access sidereal calculations, dashas, and traditional yogas
- BaZi (Four Pillars) API surface: Complete Chinese astrological analysis including earthly branches, heavenly stems, and 10-year luck pillars
- Advanced Angular Paran Engine (Scale Tier): High-fidelity cross-chart relational parans and CCG temporal parans with temporal crossing resolution
- Comprehensive Chart Comparison (BiWheel): Added API and MCP support for Secondary Progressions, Solar Returns, Lunar Returns, and Solar Arc Directions with mode-aware synopses
△Improved
- Expanded overall API coverage by +18 public endpoints (bringing the total to 118)
Accuracy and schema fixes — corrected Chiron orbital elements, house system selection, and progressed chart field mapping
△Improved
- Progressed chart metadata now includes proper ISO datetime fields and calculation metadata instead of raw Julian Day numbers
- Progressed chart house system respects the configuration.house_system field instead of defaulting to Placidus
⬡Fixed
- Progressed chart endpoint now returns fully populated planet fields (sign_name, sign_longitude, longitude_speed, is_retrograde) — previously lost during an internal serialization step
- House system selection works with human-readable names (whole_sign, koch, campanus, etc.) in addition to single-letter codes — clients sending house_system at the request root are now handled correctly
- Chiron and Pholus positional accuracy improved by updating Keplerian orbital elements to JPL Horizons J2000.0 epoch values, reducing propagation error for historical charts
Professional BaZi analytical engine — six new Chinese astrology endpoints, 24 Solar Terms, and MCP v3.9.2
＋Added
- GET /chinese/bazi/{date}/ten-gods — Ten Gods (十神) analysis: every stem in the chart related to the Day Master using the full 10×10 polarity matrix
- GET /chinese/bazi/{date}/luck-pillars — Luck Pillars (大運): ten-year cycles computed from solar term distance at the traditional 3-days-per-year rate
- GET /chinese/bazi/{date}/annual-pillar — Annual Pillar (流年): current year sexagenary overlay with clash and combination analysis against the natal chart
- GET /chinese/bazi/{date}/compatibility — BaZi compatibility (八字合婚): structural relational analysis of two natal charts including Six Clash detection
- GET /chinese/bazi/{date}/element-balance — Wu Xing element balance: Five Element distribution across stems and branches with Day Master strength assessment
- GET /chinese/solar-terms/{year} — All 24 Solar Terms (節氣) for any year, computed from the ephemeris engine to the exact minute
△Improved
- BaZi math engine now includes bazi_hidden_stems.go, bazi_ten_gods.go, bazi_nayin.go, bazi_luck_pillars.go, bazi_compatibility.go, and bazi_element_balance.go — all validated against 56 canonical reference cases
- AllSolarTermsForYear resolves all 24 Jieqi via bisection against the DE440 ephemeris — consistent with natal month pillar computation by construction
- Advanced BaZi endpoints priced at 3 credits (on par with comparative math); basic natal BaZi remains 1 credit
- MCP server updated to v3.9.2 — BaZi analytical tools available to Claude and all MCP-compatible AI agents
- Total public API surface: 116 endpoints across Western, Vedic, Human Design, astrocartography, Chinese, and astronomical calendar traditions
Human Design body graph API, visual chart deliverables, expanded transit bodies, and MCP v3.8.0
＋Added
- POST /human-design/chart — full body graph data: gate and channel activations, defined centers, type, authority, profile, and incarnation cross
- POST /visualization/bodygraph — server-rendered SVG and PNG body graph image (Pro tier+)
- human_design_bodygraph MCP tool — AI assistants can now request rendered body graphs directly
- POST /human-design/composite — composite connection chart for two subjects
- POST /human-design/transit — transiting gates and channels overlaid on the natal design
- POST /human-design/cycles/solar-return, /cycles/return, /cycles/opposition — Human Design life cycle charts
- POST /human-design/penta — group field penta computation
- include_visual: true flag on natal and HD chart endpoints — returns embedded SVG or PNG in a single API response
- Chiron, True Node, South Node, Lilith, and Ceres added to the /predictive/transit-chart body catalog
- All ephemeris kernels bundled into the Docker image — enables horizontal scaling without shared file storage
△Improved
- MCP server updated to v3.8.0 with readOnlyHint annotations for Anthropic directory compliance
- MCP README expanded with full tool surface documentation and setup instructions
⬡Fixed
- Human Design 10-57 channel was not rendering in body graph output
- Duplicate point geometries for Lilith/Nodes resolved via native EclipticToEquatorial fallback
- Chiron mathematical drift resolved
Relocated cardinal angles, True Lilith math fix, and documentation improvements
＋Added
- Cardinal angles (AC, DC, MC, IC) in /acg/local-space with azimuth, altitude, and above-horizon metadata
△Improved
- Documentation page redesigned with text-reveal animations and shimmer copy buttons
⬡Fixed
- True Lilith (OscuLilith) now computed from orbital state vectors — previously crashed the Go sidecar
- MeanNode, MeanLilith, and TrueNode RA/Dec zeroed in analytical path (OE-NODE-001)
- Midpoint features returned empty in /acg/features (OE-MIDPOINT-001)
BSP asteroid precision, draconic charts, and predictive time-lord endpoints
＋Added
- 12 sb441-n16 perturber bodies exposed via high-precision BSP asteroid integration
- Draconic chart, prenatal lunation, and primary directions endpoints — 107 total API surface
- Profections and Firdaria time-lord endpoints wired end-to-end with sect-aware overrides
- Pholus (SE ID 16) added to natal chart body list
△Improved
- Time-lord sect and Lot overrides finalized; return charts now hydrated with full chart data
- Pholus and Chiron upgraded to high-precision sb441-n16 ephemerides
- MCP server tool surface expanded with full README documentation
⬡Fixed
- Pholus mapping fix and res variable scoping in make_ephem_object branch
- NAIF ID routing (2000000+N) corrected for asteroid lookups
- SuperNOVAS compilation fixed with absolute path for Go sidecar
MCP registry submission, billing tier corrections, and public surface audit
＋Added
- MCP server published to Smithery registry with full tool surface documentation
- Health catalog endpoints opened to free tier for API discoverability
- Landing page redesigned — AI API explicitly positioned as the Master Astrologer endpoint
△Improved
- Public surface audit — README rewrite, gitignore cleanup, stale endpoint counts corrected across all meta tags
- OpenAPI spec synced and equivalence-tested against live schema
- MCP allowlist regenerated and test thresholds updated
⬡Fixed
- /ephemeris/schemas/natal-request and /ephemeris/supported-metadata set to 0 credits (were incorrectly billable)
- Delete-account flow: hard-delete FK-referencing rows before auth user deletion
- Annual savings label corrected to 24%
- .vercelignore pattern fixed — was stripping components/dev/ from production build