Transits to a natal chart now cost 1 credit instead of 3.
△Improved
- PRICE CUT: `POST /comparative/natal-transits` (a birth chart, the sky at a moment you choose or right now, and every aspect between them) costs 1 credit a call instead of 3, from this release. Nothing changes in the request or the response. Synastry, composite and overlay stay at 3 credits. In Claude and ChatGPT this is the `ephemeris_natal_transits` tool.
The sky over a place: rise and set times and tracks for any planet, star or the Galactic Center, every twilight and golden and blue hour, the moonless dark window, and the ecliptic, galactic plane and house divisions drawn on the sky. Five new routes, all on the free tier.
+Added
- `GET /sky/rise-set`: when anything rises, sets and culminates, day by day for up to a year: the Sun, Moon and planets, any of the 100 catalog bodies, the catalog stars, and the Galactic Center. Rise and set come with their compass direction. Add `min_altitude` to get when it stands above a height, for example the Milky Way core above 10 degrees. 1 credit per 10 body-days.
- `GET /sky/track`: where a body is in the sky, step by step between two times: altitude and direction, with or without atmospheric refraction (adjustable for air pressure and temperature), plus disc size, lit fraction, phase and the angle of the lit edge for the Moon and planets, and planet brightness. 2 credits a call, up to 10,000 points.
- `GET /sky/light`: the light of each day: astronomical, nautical and civil dawn and dusk, sunrise and sunset with direction, golden and blue hour, solar noon, day length, moonrise and moonset, and the dark window, when the night is fully dark and the Moon is down. Golden hour (Sun between -4 and +6 degrees) and blue hour (-6 to -4) are photographers' conventions, stated in every response. 1 credit per 7 days.
- `GET /sky/light-at`: the light at one moment: day, twilight or night, golden or blue hour, where the Sun and Moon are, and the nearest change before and after. Useful for "was it dark when this was taken?". 1 credit.
- `GET /sky/circles`: the ecliptic, the celestial equator and the galactic plane as paths across the sky for a place and time, and, with a house system, the house cusps and the lines where each house begins (Placidus, Campanus, Regiomontanus). 1 credit.
- Every `/sky` response carries a `method` block naming the ephemeris, the time scale, the refraction model, the horizon and the conventions, so a result can be cited.
△Improved
- `GET /time/solar-event` now lists nautical and astronomical twilight as well as civil.
- Checked against the US Naval Observatory and JPL Horizons: rise, set and twilight times agree to the minute those sources print, positions to within 2 arcseconds.
A catch-up entry for what reached the assistants and the API since 4.6.0 and was only in the API and MCP changelogs: sky recurrence, a credits card, sign change dates, a Human Design gate timeline, relationship and sidereal wheels, and three chart corrections marked CHANGED NUMBER below.
+Added
- `POST /predictive/sky-recurrence`: the last and next times Jupiter, Saturn, Uranus, Neptune and Pluto (or any subset) all stand again within an orb of their birth longitudes at once, searched exhaustively over 1550 to 2650, with the closest sky on each side of birth. Tropical or sidereal (Lahiri). Priced by the span you search. Live since 2026-10-25.
- MCP: `account_usage` opens a card in Claude and ChatGPT with credits left, credits used each day for 14 days, the tools that used the most, and what common calculations cost. In ChatGPT and Codex, after an out-of-credits answer the server pauses repeat calls for two minutes instead of letting the assistant retry.
- MCP: `ephemeris_ingresses` (when a planet changes sign, when the Moon is next in a sign, every time a planet crosses an exact degree) and `human_design_transit_timeline` (every gate each transiting body enters and leaves over a range, and the windows that complete your channels) are in the default tool list.
- MCP: `explore_bi_wheel` draws composite (midpoint) and Davison wheels and takes a `house_system`; `explore_natal_chart` takes `zodiac_type` and `ayanamsa` for a sidereal wheel.
- MCP: `find_calculation` and `dev_write_api` are in the default tool list in Claude, so calculations without a typed tool (KP, Varshaphal, the Chinese calendar, bounds, eclipses on a chart, sky recurrence) are one question away. ChatGPT does not see these generic tools.
- Birthplaces typed in their own script ("Москва", "東京") now resolve.
△Improved
- CHANGED NUMBER: sect in natal, progressed and relocated charts, hermetic lots, dignities, primary directions, distributions, time lords, electional, mundane charts and the heatmap now comes from the horizon. With Placidus and the other quadrant systems outside the polar circle nothing changes.
- CHANGED NUMBER: the Ascendant, and the houses and sect built from it, change for charts inside the polar circle (above about 66.6 degrees). Charts outside it do not change.
- CHANGED NUMBER: the Vertex moves in natal charts, wheels, angles and points, draconic charts, local space and Vertex lines for births in the tropics (within about 23.4 degrees of the equator). Heatmap `AlgorithmVersion` is 3.11.0.
⬡Fixed
- Day or night chart (sect) is read from the horizon, not the Sun's house. With whole-sign houses a Sun in the rising sign that had already risen was called a night chart, which gave the night Lot of Fortune, the wrong sect light and the wrong in-sect planets.
- The Ascendant is the rising degree at every latitude. Inside the polar circle it was the setting degree for part of each day. It now follows Swiss Ephemeris.
- The Vertex is always in the west. Within about 23.4 degrees of the equator it was the Anti-Vertex for part of each day.
Find a good date for a group: one new route scores election hours against up to 8 birth charts as well as the sky. In the chat, one electional tool now covers no one, one person or a group, with a timeline widget, and a new time-lords widget draws zodiacal releasing, profections and firdaria. One price changed; it is marked CHANGED NUMBER below.
+Added
- `POST /electional/group-window` (Pro): the best windows for 1 to 8 people at one event place. Each hour is read as an election chart (the Moon, the Ascendant ruler, benefics and malefics on the angles), then checked against every person's chart. An hour is ruled out when Saturn or Mars is within 2° of a conjunction, square or opposition to anyone's Sun, Moon, Ascendant or Ascendant ruler, when the election Ascendant is within 3° of anyone's natal Mars or Saturn, or when the Moon is within 15° of the Sun. People are combined by the weakest score (2-3 people), half weakest and half average (4 or more), or `average`, then blended 50/50 with the sky. Only hours from `earliest_local_hour` to `latest_local_hour` (default 8 to 21) are searched, and at most one window per local day is returned. `time_known: false` compares planets only for that person. Every weight, veto and orb is published in `search_summary`. Price: the find-window price for the span (5 / 8 / 12) + 4 + 1 per person after the second, so 9 credits for 1 or 2 people over 30 days or less. Longest range: Pro 30 days, Startup 60, Scale 120.
- MCP: `ephemeris_electional` is now the one electional tool. With no people it searches the sky alone (`/electional/find-window`, unchanged). With 1 to 8 people it calls `/electional/group-window` and opens the Group timing widget: the windows on a time axis with the best three starred, one row per person showing good and vetoed hours with the reason for each veto, and ranked cards with the sky's case for and against each window and each person's contacts. The widget shows in ChatGPT and Claude.
- MCP: `explore_time_lords`, a time-lords widget. Zodiacal releasing from the Lot of Spirit or Fortune (level 1 over the whole life, level 2 inside the chosen period, peaks and Loosing of the Bond marked), the profection wheel and year lord, and firdaria, drawn as one timeline in the chat, with the changes to come listed by date. Dates show in the birth time zone. It uses the existing `/predictive/time-lords/*` routes and shows in ChatGPT and Claude.
△Improved
- CHANGED NUMBER: `/electional/find-window` reads minute-precision zoned times (`2026-11-01T09:30-05:00`) and space-separated times when it prices the span. Before, those fell back to the lowest price, so a long range written that way could cost 5 credits instead of 8 or 12. The search results are unchanged, byte for byte.
Vedic panchang, KP and Tajika Varshaphal, Vedic strength and two more dashas, the Chinese lunisolar calendar, the sky tonight, your biggest transits ranked, eclipses that hit your chart, supermoon and crescent visibility, directing through the bounds, and traditional points. Every addition is a new route or an opt-in field. Some existing numbers changed; each is marked CHANGED NUMBER below.
+Added
- `POST /vedic/panchang`: the panchang of one local day at one place, sunrise to the next sunrise. Every tithi (with paksha), karana, yoga and nakshatra in force that day with its exact start and end, the vara and its lord, the Sun's and Moon's sidereal signs at sunrise, and Rahu Kaal, Yamaganda, Gulika and Abhijit muhurta. Checked against Drik Panchang at New Delhi, New York, Reykjavik in June and Tokyo: every name matches and every time is within 2 minutes (Drik prints minutes).
- `POST /vedic/kp`: a Krishnamurti Paddhati chart. Sidereal Placidus cusps and the nine grahas with sign, star, sub and sub-sub lord and KP number (1-249), significators both ways, Rahu and Ketu as agents, and the five ruling planets. `horary_number` (1-249) casts a KP horary chart. KP old (`krishnamurti`, the default) and the new ayanamsa `krishnamurti_vp291` (KP new). Checked against a published sub-lord table (all 249 boundaries, to the second), the AstroSage KP worked chart, KP Reader VI's horary numbers 237 and 48, and Swiss Ephemeris.
- `POST /vedic/varshaphal`: the Tajika annual chart for one year. Varsha Pravesh (within 5 seconds of Swiss Ephemeris), Muntha, the five office-bearers and the year lord, Pancha-vargiya bala, Tajika aspects with Ithasala and Isharaf, the fifty sahams, and the Mudda dasha. Rules follow the Samjnatantra as given in Balabhadra's Hayanaratna; where classical authorities differ, a field picks the variant and `metadata.conventions` names every rule used.
- `POST /vedic/chart` takes `include: ["ashtakavarga", "shadbala", "bhava_bala"]` and `dasha.system: "yogini"` or `"chara"`. Shadbala reproduces B.V. Raman's worked example sub-bala by sub-bala. Chara dasha has three schools (`chara_method`: `kn_rao`, the default; `pvr`; `rath`). With Ashtakavarga, `sodhita` gives the reduced rows and pindas; with Shadbala, Ishta and Kashta phala. Every dasha period now has `lord_ids` and local start and end times.
- Vedic names: every named item on the panchang, KP and Varshaphal routes has a stable `id` plus `name`, `name_iast` and `name_devanagari`.
- `POST /chinese/calendar/convert` and `POST /chinese/calendar/almanac`: Gregorian to Chinese lunar date and back (with leap months), the year, month, day and hour pillars, the solar terms at their exact instants, and the Tong Shu basics (day officer, 28 lodges, clash, sha). The almanac returns one Gregorian month. Computed from DE440 new moons and solar terms, Chinese New Year 1645 to 2648-12-31. Every Chinese New Year and every leap month 1901-2100 matches the Hong Kong Observatory; 2,467 of 2,473 months and 4,792 of 4,800 solar-term dates agree, and the rest fall within 26 minutes of midnight. Names in simplified and traditional Chinese and pinyin.
- `GET /ephemeris/sky-tonight`: rise, set and culmination of the Sun, Moon and planets for a date and place, which planets can be seen that night and when, magnitude and elongation, close approaches with the Moon, and the Moon covering a planet or bright star. Times are local. Rise, set and culmination within 30 seconds of JPL Horizons at Greenwich.
- `POST /predictive/transits/search` takes `sort=significance`: every natal hit scored and ranked, with the score's parts shown. `group=episodes` folds a retrograde double or triple pass into one entry.
- `POST /predictive/eclipses/natal-hits`: the eclipses in a date range that fall on natal points, with the aspect and orb, and with a `location`, whether and how each can be seen there.
- `GET /ephemeris/moon/crescent-visibility`: when the new crescent Moon can be seen from a place, over three evenings, with Yallop's q-test and Odeh's V criterion side by side. Every response says it is an astronomical prediction, not a religious ruling. 32 of 32 city-evenings match ICOP's published Odeh maps for Ramadan and Shawwal 1446 and 1447.
- `GET /ephemeris/moon/phase` adds the previous and next perigee and apogee (within 1 second and 0.05 km of JPL Horizons) and the next supermoon and micromoon, with a choice of definition (`orbit_90` or `year_90`). The moon-phase calendar and `/tidal/forcing` carry the same distances.
- `POST /predictive/time-lords/distributions`: directing through the Egyptian bounds from the Ascendant (or MC, Sun, Moon, Fortune), with the distributor and partner of each period and its ages and dates. Arcs match Swiss Ephemeris within 0.1 arcminute.
- `POST /ephemeris/natal-chart` opt-ins: `traditional_points` (Almuten Figuris by Ibn Ezra's five places, hayz, the Moon's Arabic lunar mansion), `custom_lots` (up to 12 lots from your own formulas, also on `/ephemeris/hermetic-lots`), `include_gauquelin_sectors` (within 0.003 sector of Swiss Ephemeris) and `include_aspect_perfection` (the exact time each aspect perfects, within 0.04 minutes of JPL Horizons).
- `POST /ephemeris/prenatal-lunation` `include`: `planet_syzygies` and `eclipses` (the prenatal eclipse with its saros series, and the same-series eclipses during the life).
△Improved
- CHANGED NUMBER: term dignity uses the Egyptian terms of Ptolemy (Tetrabiblos I.20). Seven signs had the wrong boundaries. A planet in a changed degree gains or loses its +2 term dignity, and heatmap scores move with it (`AlgorithmVersion` 3.10.0; in a sample chart about a fifth of cells moved, mostly by 1 or 2 points).
- CHANGED NUMBER: penumbral lunar eclipses are now found by `/eclipse/next`, `/eclipse/next-visible` and `/eclipse/lunar/global` (the penumbra had the wrong sign). Lunar eclipse magnitudes move by about 0.01.
- CHANGED NUMBER: solar eclipse times are UTC. They were about 69 seconds late (Terrestrial Time printed as UTC). Besselian element rates were 86,400 times too small; both are fixed.
- CHANGED NUMBER: `/tidal/forcing` `perigee_status` now comes from the geocentric distance between the nearest perigee and apogee, and `days_to_perigee` is the real count (it was always -1).
- CHANGED NUMBER: `/electional/moment-analysis` `day_ruler` follows the planetary day, local sunrise to the next sunrise, when coordinates are sent. `dignity_label` now says `triplicity`, `term` or `face` where it said `peregrine`.
- CHANGED NUMBER: `/ephemeris/prenatal-lunation` reads the birth time, not only the date, so a birth near a lunation gets the right one. A naive clock time now needs `timezone`.
- Human Design never falls back to "88 days before birth" when the Design instant search fails; the request is refused instead. `/human-design/penta` refuses (and refunds) a member whose chart cannot be built instead of dropping it and charging.
- Chiron and Pholus returns outside their kernel window answer a 422 naming the window instead of a vague error.
- `/ephemeris/progressed` returns a 422 naming a field it does not support instead of ignoring it. Minor and angle aspects, the declination options and `ascendant_on_left` now work.
⬡Fixed
- Devanagari and Bengali now render correctly in PNG chart images. BaZi and Zi Wei PNG charts now draw their Chinese characters (they were empty boxes).
- Eclipse search no longer skips lunations near a stalled solver step; it had dropped some eclipses (for example 1997-03-09 and 2015-03-20) from series searches.
- `/tidal/forcing` now returns `equilibrium`, which it documented but never sent.
- `Cache-Control` and `ETag` are now sent on the deterministic routes. They were set after the response had gone out.
Human Design Dream chart: `chart_variant` on `POST /human-design/chart`. Nothing changes for a request that does not send it.
+Added
- `POST /human-design/chart` accepts `chart_variant`: `waking` (the default, unchanged) or `dream`. A Dream chart casts the Design side at the moment the Moon stood 88 degrees behind its birth position (about 5.7 to 7.5 days before birth) and counts only 15 gates (1, 5, 8, 12, 15, 19, 20, 27, 28, 38, 42, 50, 53, 57, 62). Channels and centers come from those gates only; there is no Type, Authority, Profile, Strategy, Definition or Incarnation Cross. All 26 activation rows are kept, each marked `in_variant`.
- `metadata.design_epoch` says how the Design instant was found (body, arc, days before birth, basis) and `metadata.gate_set` names the gate set. The basis is `vendor_parity`: the Dream output matches one vendor's published tables for every birth we compared (six births, all 15 gates), and no second source has been compared yet.
- The `/iching/chart` alias takes the same field. `format=llm` keeps the fixed-width activation rows and lists only the rows inside the gate set, with `chart_variant` and `days_before_birth` on the header.
△Improved
- The epoch search for a Dream chart returns an error rather than a guess if it cannot find the instant (the standard chart's Design search falls back to 88 days; the variant search never does).
- A Dream request costs the same as a standard chart, 2 credits, and any 422 is refunded.
Sunrise, sunset and the Moon's rise and set now belong to the right local day, moonrise and moonset are within about a minute of JPL Horizons, and progressed charts say when a body could not be read. Three of these change numbers existing callers can see; each is marked CHANGED NUMBER below.
+Added
- `GET /time/solar-event` and `GET /ephemeris/agro/daily` take an optional `timezone` (an IANA zone name such as `Asia/Tokyo`). When you send one, the day is that zone's civil day, midnight to midnight on its clock (23 or 25 hours across a clock change), so the times are the ones a local almanac lists for the date. A name that is not an IANA zone is a 422.
- Both routes now return `day_basis` (`civil_tz` or `local_solar`) to say which day was used: in `information` on `/time/solar-event` and in `horizon` on `/ephemeris/agro/daily`. `/time/solar-event` also returns `information.day_start` and `information.day_end` (the UTC window it searched) and `information.timezone` when you named one.
- `POST /ephemeris/progressed` now returns `metadata.omitted_bodies`, naming any body whose position could not be read at the progressed instant (for example Chiron outside its kernel range). Such a body used to vanish from `planets` with nothing to say so. It is absent when nothing was dropped.
△Improved
- CHANGED NUMBER: sunrise, sunset and the civil twilights on `/time/solar-event` and `/ephemeris/agro/daily` are now found on the local day, not the UTC day. The search used to run from 00:00 to 24:00 UTC at every longitude, so for places far from Greenwich the sunrise or sunset returned was the neighbouring local day's, with no error. Without `timezone` the day is now the local mean solar day at the longitude (24 hours from local mean midnight). Checked against JPL Horizons for Tokyo, Kolkata, Chicago, London, Sydney and Tromsø on 2026-06-21 and 2026-12-21: 6 of 20 sunrise and sunset events were on the wrong local day (Tokyo, Kolkata and Sydney sunrise, and Chicago's June sunset); all 20 now match to within Horizons' one-minute resolution. Those events move by exactly one day. Events that were already on the right day move by under a second.
- CHANGED NUMBER: moonrise and moonset in `/ephemeris/agro/daily` use the same day, and are now 4 to 12 minutes earlier (moonrise) and later (moonset) than before. The search compared the Moon as seen from the observer with the cutoff for the Moon as seen from the centre of the Earth, so its parallax of about 0.95 degrees was counted twice. Against Horizons (22 events, same cities and dates) the old values were 6.1 minutes off on average, worst 11.7, moonrise late and moonset early; the new ones are 0.46 minutes off, worst 1.0. This is separate from, and larger than, the Delta T effect described under 4.3.0. Without `timezone`, an event within about an hour of local midnight can still fall on the neighbouring civil date; send `timezone` for the civil day.
- CHANGED NUMBER: `metadata.day_year_ratio` on `POST /ephemeris/progressed` is now returned only for `secondary` and `solar_arc`, the two methods that read it. For `tertiary` and `minor` it used to echo `1.0`, a number the chart never used.
- The `/ephemeris/agro/daily` description no longer claims "±1s precision". It says the times agree with JPL Horizons to within about a minute, which is what was measured.
- Unchanged: planet positions, the solar transit time, the `elev` behaviour, `/ephemeris/agro/calendar` and every other route.
Six new endpoints (geodetic charts, mundane ingress and lunation charts, Zi Wei Dou Shu, Vedic Ashtakoota matching, birth-time sensitivity, an N-person Human Design connection matrix), plus Vimshottari dashas and divisional charts on the Vedic chart, Uranian dial tools on midpoints, a selectable coordinate frame, and nth returns. Five numbers existing callers can see have changed; they are listed under Improved.
+Added
- `POST /human-design/connection-matrix` (2 credits per subject, 3 to 12 subjects): the four connection types for every pair, N x N matrices, per-person summaries and group set operations. It reports mechanics only and does not name groups.
- `POST /ephemeris/geodetic` (1 credit): a place's geodetic Midheaven (east longitude is its zodiac degree), Ascendant, 12 cusps and sign zone. With `date_time` it adds planets in those houses and contacts to the four angles. `zodiac_type: sidereal` shows the tropical geodetic chart in the sidereal zodiac and says so in the response.
- `POST /mundane/chart` (2 credits): a chart cast at the exact Sun sign ingress, or the next New or Full Moon, for a place you choose. Validity and lord-of-the-year candidates are labelled facts for the four cardinal ingresses only.
- `POST /chinese/ziwei` (2 credits): a Zi Wei Dou Shu natal chart for years 1551 to 2648. Birth hour and gender are required. The leap-month rule, day and year boundary and four-transformation choices can be overridden, and the response echoes what was applied.
- `POST /vedic/matching` (2 credits): the 36-point Ashtakoota (Guna Milan) match of two charts. Nadi, Bhakoot and Gana doshas and the Manglik placement come back as facts with the classical cancellation conditions listed; no cancellation is applied to the score and no verdict is given.
- `POST /ephemeris/time-sensitivity` (2 credits): every sign and house boundary inside a birth-time window, with a stable, fragile or unstable verdict for each fact. It shows how much an uncertain birth time matters; it does not rectify a chart.
- `/vedic/chart` now returns `dasha` (Vimshottari periods to depth 3, and the periods running at `as_of_utc`) when asked. `year_basis` chooses the year length and the response echoes it.
- `/vedic/chart` now has a `node_type` option (`mean` by default, `true`) that decides which lunar node Ketu follows, a `roster` option (`classical` returns only the nine Jyotish grahas), a `Ketu` row, and the nakshatra deity on every planet (it was always empty).
- `/vedic/chart` now returns `vargas` when asked: the lagna and every planet in D1, 2, 3, 4, 7, 9, 10, 12, 16, 20, 24, 27, 30, 40, 45 and 60 (Parashara reading).
- `/ephemeris/midpoints` accepts an opt-in `uranian` block: dial sort, focal tree and planetary pictures on a 360, 90, 45 or 22.5 degree dial, with the eight Hamburg points and the Aries Point.
- `configuration.coordinate_system` is now honoured on natal, planet-position, transit-chart and batch: geocentric (default), topocentric, and on natal and planet-position also heliocentric and barycentric (no angles or houses in those frames). A combination a route cannot answer is a 422 that lists the valid choices.
- Nth and fractional returns on the Human Design cycle routes, circuits and sub-circuits on Human Design chart, composite and penta, and `converse` and `minor` progressions with `metadata.progression_key`.
△Improved
- CHANGED NUMBER: `method: tertiary` on progressions now computes Tertiary I (about 13.37 ephemeris days per year). It used to be keyed at 27.32 days per year, which is a minor progression. If you relied on the old numbers, send `method: minor`.
- CHANGED NUMBER: sidereal longitudes now follow the Swiss Ephemeris ayanamsha definitions for all five systems (lahiri, fagan_bradley, krishnamurti, raman, yukteshwar). Lahiri was about 19.5 arcseconds too high in 2026 (up to 31 arcseconds across 1600 to 2600), and Krishnamurti, Raman and Yukteshwar were 28 to 54 arcseconds off. Vimshottari dasha dates move by up to about 3 days. The echoed ayanamsa value changes by the same amount.
- CHANGED NUMBER: an unrecognised `ayanamsa` is now a 422. It used to be computed as Lahiri while your label was echoed back.
- CHANGED NUMBER: Vedic `bhavas` are now the sidereal lagna's whole signs. They used to keep the tropical sign edges (about 5.8 degrees off), and slot 0 held a placeholder; it is now 0.
- CHANGED NUMBER: observer-based positions use the corrected Delta T, which had been passed in days instead of seconds. Topocentric Moon positions, moonrise and set, local space and eclipse local circumstances move by up to about 13 arcseconds.
- CHANGED BEHAVIOUR: `/ephemeris/planet-position` with `latitude` and `longitude` for a Uranian or element-only body is now a 422 (`unsupported_in_frame`) instead of a geocentric answer under a topocentric label. A progressed target before birth, `day_year_ratio` outside 0.1 to 5, `day_year_ratio` with tertiary or minor, and an unsupported house system for progressions are also 422s.
- Unchanged: default geocentric natal output is byte-identical to the previous release, and default `/ephemeris/midpoints` output is too.
Charts now say how each lunar node was computed, and the Delta T model behind every position was corrected to the published Stephenson, Morrison and Hohenkerk table. The Delta T fix moves the Moon by up to about 15 arcseconds for 17th-century births and by about an arcsecond or less since 1900; the Ascendant and houses do not move.
+Added
- Natal-chart, progressed and relocation responses now include `calculation_metadata.lunar_nodes`, which states how each lunar node and apogee in the response was computed, by name. `North Node (True)` is `true_osculating`: the Moon's osculating node, taken from its instantaneous orbit in the true ecliptic of date, the equivalent of Swiss Ephemeris `SE_TRUE_NODE`. `North Node (Mean)` is `mean`. Each South Node records which North Node it mirrors. The `true_node` body always selects the True node, never the Mean node, and every tier receives the same metadata.
- `calculation_metadata.node_source` is now returned. It was declared in the spec from the start but never populated. It echoes `configuration.node_source` when you send one; otherwise it names the nodes the chart carries, which is `mean_and_true_osculating` for the default roster that returns both North Nodes.
⬡Fixed
- Delta T was wrong, and is now the published model. Every response is stamped `delta_t_source: stephenson_2021`, but the model behind it was a hand-made table that disagreed with the Stephenson, Morrison and Hohenkerk fit by up to 1.6 s in the modern era, 4.5 s in the 1800s, 6.4 s in the 1700s and 27.5 s in the 1600s, and it dropped off a 121-second cliff at the year 2120. It now evaluates the published Table S15 directly. Checked against an independent implementation (Skyfield), it agrees to within 0.01 s from 1600 to 1955 and to within 0.32 s of observed values since.
- What that moves: the Moon travels about 0.55 arcsecond per second of Delta T, so lunar longitude, and anything derived from it, changed by up to about 15 arcseconds for charts in the 1600s, about 2.5 arcseconds in the 1800s, and an arcsecond or less from 1900 to 2025. The Ascendant, Midheaven and houses do not move, because they use UT1. Beyond 2120 Delta T is the authors' long-term extrapolation and is uncertain by construction.
- `GET /ephemeris/supported-objects` now lists `true_node`, `lilith_true` and `lilith_interpolated`, which the spec has always accepted, and `GET /ephemeris/supported-metadata` no longer advertises DE441, which is not served.
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 Open Ephemeris 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
- POST /chinese/bazi/ten-gods — Ten Gods (十神) analysis: every stem in the chart related to the Day Master using the full 10×10 polarity matrix
- POST /chinese/bazi/luck-pillars — Luck Pillars (大運): ten-year cycles computed from solar term distance at the traditional 3-days-per-year rate
- POST /chinese/bazi/annual-pillar — Annual Pillar (流年): current year sexagenary overlay with clash and combination analysis against the natal chart
- POST /chinese/bazi/compatibility — BaZi compatibility (八字合婚): structural relational analysis of two natal charts including Six Clash detection
- POST /chinese/bazi/element-balance — Wu Xing element balance: Five Element distribution across stems and branches with Day Master strength assessment
- POST /chinese/bazi/solar-terms — 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