account_usage
ChatGPTUse this when the user asks 'how many credits do I have left', 'what's my usage this month', 'am I close to my limit', 'what plan am I on' or 'how do I upgrade or top up'. Returns plan tier, billing period, credits used / included / remaining, percent of quota used, total API calls, and subscription status with renewal date; pass month='YYYY-MM' for a past period. CREDIT COST: 0.
acg_hits
ChatGPTUse this when the user asks 'is Tokyo good for me', 'where should I live according to my chart', 'what planets affect me in Paris', 'which of my lines run through Lisbon' or 'should I move to Austin'. Returns every astrocartography line (power lines and aspect lines) within radius_deg of a query location, sorted by distance, for a given birth chart. CREDIT COST: 10 credits per call. Pro tier.
acg_power_lines
ChatGPTUse this when the user asks 'show my astrocartography map', 'where are my Jupiter lines', 'where in the world is my Sun on the MC', or wants the whole-world list of their lines. Returns, per planet, its MC, IC, AC and DC lines (where it was culminating, anti-culminating, rising or setting at birth) with sign and equator-crossing longitude — geometry stripped, not for map rendering. CREDIT COST: 10 credits per call. Pro tier.
bazi_annual_pillar
ChatGPTUse this when the user asks 'what element is the year of the Snake', 'what's the pillar, stem and branch or NaYin for my birth year' or 'what's the energy of this year' — a single-year lookup beyond the animal. Returns the year's Heavenly Stem, Earthly Branch, Chinese characters, zodiac animal, element, polarity and NaYin (纳音) resonance image for any Gregorian year 1-9999. CREDIT COST: 3 credits per call.
electional_moment_analysis
ChatGPTUse this when the user asks 'is now a good time to …', 'what's the sky doing today', 'what's the astrological weather', 'how is this date astrologically' — or has no birth data (it works with no arguments). Returns planet positions, aspects, void-of-course status, lunar phase, day ruler, sect and an overall electional score (0-100) for one moment. CREDIT COST: 5 credits per call.
electional_station_tracker
ChatGPTUse this when the user asks 'when does Mercury go retrograde', 'when does Mercury retrograde end', 'when does Mars go direct', 'when does Pluto go direct', 'is Venus retrograde this year', 'Mercury retrograde dates for 2026' or 'what planets station this month'. Returns every retrograde and direct station in the range with exact time, longitude and sign — Mercury through Pluto; default range the next 90 days, maximum one year. CREDIT COST: 5 credits per call.
ephemeris_angles_points
ChatGPTUse this when the user asks 'where is my Vertex', 'what's my East Point / equatorial ascendant' or 'what are my chart angles' for a date, time and place. Returns ASC, MC, DSC, IC, Vertex and the Equatorial Ascendant/Descendant; the equatorial ascendant is also returned under east_point — a synonym for the same point, not a separate one. CREDIT COST: 1 credit per call.
ephemeris_aspect_check
ChatGPTUse this when the user asks 'is 15° Aries square 18° Cancer', 'what aspect is between these two positions', 'how many degrees apart are my Sun and Moon' or 'is this within orb'. Returns the angular separation between two ecliptic longitudes (longitude_1, longitude_2) and any aspect within orb (conjunction, sextile, square, trine, opposition, etc.). CREDIT COST: 1 credit per call.
ephemeris_electional
ChatGPTUse this when the user asks 'when is the best time to launch / sign / marry / start X' within a date range, 'find me a good day next month' or 'pick an auspicious window'. Returns the best continuous timing windows in the range, scored hourly on essential dignity, aspect quality, sect and void-of-course Moon penalties, with optional filters (avoid_voc, lunar_phase). CREDIT COST: ≤30 days 5, ≤60 days 8, ≤120 days 12. Pro tier; max window Pro 30 days, Startup 60, Scale 120.
ephemeris_house_cusps
ChatGPTUse this when the user asks 'what are my house cusps', 'where does my 7th house start', 'show my houses in Whole Sign' or 'compare Placidus and Koch for my chart' — houses and angles only, for a date, time and place. Returns the twelve cusps and ASC/MC/DSC/IC for each requested system. HOUSE SYSTEM CODES: P=Placidus, K=Koch, O=Porphyry, R=Regiomontanus, C=Campanus, E=Equal, W=Whole Sign. CREDIT COST: 1 credit per call.
ephemeris_moon_phase
ChatGPTUse this when the Moon's state is wanted as data for a specific moment — 'what phase was the Moon on my birthday', 'what sign was the Moon in on 12 May 1990', 'moon phase and illumination as numbers'. Returns phase name, illumination %, the Moon's sign and degree, and the next void-of-course window; omit datetime for right now. CREDIT COST: 2 credits — phase and void-of-course are metered separately (the phase-only endpoint /ephemeris/moon/phase costs 1).
ephemeris_natal_chart
ChatGPTUse this when the birth chart is wanted as data rather than a picture — 'give me my chart as JSON', 'list my natal aspects with orbs', 'what exact degree is my Ascendant', 'my placements as a table' — or as the input to a further calculation. Returns raw JSON: all major planets plus Chiron and the major asteroids (Ceres, Pallas, Juno, Vesta) — and, on request, any of ~90 more bodies via additional_objects (Eris, Sedna, Psyche, Hekate, Fortuna, Pandora, Asbolus and so on) — angles (ASC/MC/DSC/IC), house cusps, dignity condition, retrograde flags and the major aspect grid; format='llm' gives compact output. Takes coordinates, not a place name. CREDIT COST: 1 credit per call.
ephemeris_next_eclipse
ChatGPTUse this when the user asks 'when is the next eclipse', 'when is the next solar / lunar eclipse', 'is there an eclipse visible from Tokyo' or 'when is the next total lunar eclipse'. Returns the eclipse type, date/time of maximum, magnitude and duration of totality; with latitude+longitude it adds local contact times and visibility for that place, without them it returns the next global eclipse of that type. CREDIT COST: 1 credit per call.
ephemeris_next_lunar_phase
ChatGPTUse this when the user asks 'when is the next full moon', 'when is the next new moon', 'what date is the next quarter moon' or 'list the next 3 full moons'. Returns the exact UTC datetime of each upcoming occurrence of the requested phase (phase = new_moon | full_moon | first_quarter | last_quarter), optionally after a given date and for count occurrences. CREDIT COST: 2 credits per occurrence; count max 12.
ephemeris_planet_position
ChatGPTUse this when the user asks 'where is Mars right now', 'what sign is Venus in today', 'what degree is the Sun at', 'where was Jupiter on my birthday', 'where is the North Node' — one body at one moment — or 'what's my star sign / zodiac sign' from a birth date alone (planet_id=0; a bare date resolves to noon UTC, no location needed). Returns ecliptic longitude, latitude, distance, speed and retrograde flag. PLANET IDS: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta. NODES: id 10 is the mean North Node (mean-node polynomial); id 11 is the true North Node (osculating, referenced to the true ecliptic of date). There is no South Node id; the South Node longitude is a North Node longitude plus 180° (mod 360). CREDIT COST: 1 credit per call.
ephemeris_progressed_chart
ChatGPTUse this when the user asks 'what's my progressed chart', 'where is my progressed Moon / Sun', 'what sign has my progressed Moon moved into' or 'my solar arc directions'. Returns progressed planet positions, house cusps, aspects and retrograde status for a target date — method = secondary (1 day = 1 year, default), solar_arc or tertiary. CREDIT COST: 1 credit per call.
ephemeris_relocation
ChatGPTUse this when the user asks 'how does my chart change if I move to London', 'what's my relocated Ascendant in Tokyo' or 'recast my chart for where I live now'. Returns the natal chart re-cast for a new location — the same planetary longitudes with the houses and angles that place gives them. CREDIT COST: 1 credit per call.
ephemeris_retrograde_status
ChatGPTUse this when the user asks 'is Mercury retrograde right now', 'is Venus retrograde today', 'was Mars retrograde when I was born' or 'which planets are retrograde at the moment'. Returns is_retrograde, longitude speed and station proximity for one planet at one instant (planet_id; Mercury is planet_id=2), or for all ten planets when planet_id is omitted. CREDIT COST: 1 credit for a single planet; omitting planet_id runs all ten planets (10 credits, one per body).
ephemeris_solar_return
ChatGPTUse this when the user asks 'when exactly is my solar return', 'my solar return positions as data' or 'my solar return for 2027 as JSON'. Returns the exact moment the Sun returns to its natal longitude near the birthday and the Solar Return chart for that year; target_datetime picks the year (defaults to the current one). CREDIT COST: 5 credits per call.
ephemeris_synastry
ChatGPTUse this when the relationship comparison is wanted as data — 'list our inter-aspects with orbs', 'what aspects does their Mars make to my Venus', 'our synastry as JSON'. Returns the cross-aspects between the two charts plus both natal charts; needs each person's birth datetime, zone and coordinates. CREDIT COST: 3 credits per call.
ephemeris_transits
ChatGPTUse this when the user asks 'when is my Saturn return', 'when does Pluto square my Sun', 'when will Jupiter conjunct my Moon', 'what transits do I have next year' — any WHEN-does-a-transit-hit question, as data. Returns the exact moments transiting planets form the requested aspect to natal points over a date range. ASPECT ANGLES (aspect_angle): 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine. Saturn return → transiting_planets=['saturn'], natal_points=['saturn'], aspect_angle=0. EFFICIENCY: searches run faster when transiting_planets and natal_points are given; omitting both is slow. Default natal_points: sun, moon, mercury, venus, mars, jupiter, saturn. MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400). CREDIT COST: 1 + span price: ≤1y 5, ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70. truncated:true = partial, with the resume point in truncation.resume_from.
explore_bazi_chart
ChatGPTUse this when the user asks 'what's my BaZi', 'my Four Pillars', 'what's my Day Master', 'my Chinese astrology chart', 'what's my Chinese element' or 'my Chinese birth chart'. Returns an interactive Four Pillars (四柱命盘) explorer (inline in Claude and ChatGPT; text summary elsewhere): the Year, Month, Day and Hour pillars — each with Heavenly Stem (天干), Earthly Branch (地支), Ten God label and element color — plus the Day Master identity and a Wu Xing (五行) element balance bar; click any pillar for what it reveals about that life domain. CREDIT COST: 3 credits per call (1 base + 2 visual render).
explore_bi_wheel
ChatGPTUse this when the user asks 'are we compatible', 'compare my chart with my partner's', 'what's my horoscope for today', 'what's hitting my chart right now', 'what's my solar return chart this year' or 'my progressed chart on my birth chart' — any two-ring comparison they should SEE. Returns an interactive bi-wheel (inline in Claude and ChatGPT; text summary elsewhere): inner wheel Person 1's natal chart, outer ring by mode — synastry (Person 2's natal; needs their birthplace), transit (a date; today for a daily horoscope), progressed, solar_arc (target date), solar_return (target year), lunar_return (target month) — with cross-aspects drawn and every planet, aspect line and cusp clickable. Birthplaces may be place names (location, person2_location). CREDIT COST: 2 credits per call for most modes (1 per wheel; +1 to resolve a place name); solar_return/lunar_return modes cost 6.
explore_human_design
ChatGPTUse this when the user asks 'what's my Human Design', 'am I a Generator / Projector / Manifestor / Reflector', 'show my bodygraph', 'what's my HD type and profile', 'what's my strategy and authority' or 'what's my incarnation cross'. Returns an interactive bodygraph (inline in Claude and ChatGPT; text summary elsewhere) showing defined/undefined centers, active gates, channels, Type, Profile, Authority and Incarnation Cross, with any center or gate clickable for interpretation. Birthplace may be a place name (location). CREDIT COST: 4 credits per call (2 chart + 2 render; +1 to resolve a place name). Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.
explore_human_design_connection
ChatGPTUse this when the user asks 'are we compatible in Human Design', 'what's our connection chart', 'what channels do we make together' or 'show our composite bodygraph' — two people's HD charts overlaid. Returns an interactive two-person overlay bodygraph (inline in Claude and ChatGPT; text summary elsewhere) with every connected channel classified by HD connection theory: electromagnetic (attraction), companionship (sameness), dominance (one defines), compromise (friction). CREDIT COST: 5 credits per call (composite 3 + render 2). Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.
explore_human_design_transit
ChatGPTUse this when the user asks 'what are today's Human Design transits for me', 'what gates are being activated for me right now', 'which channels does this transit complete in my chart' or 'how is the current sky affecting my bodygraph'. Returns an interactive overlay bodygraph (inline in Claude and ChatGPT; text summary elsewhere) highlighting the channels the transit temporarily COMPLETES with the natal chart and any centers it newly defines, for now or a chosen datetime. Birthplace may be a place name (location). CREDIT COST: 5 credits per call (chart 3 + render 2; +1 per place name). Human Design was originated by Ra Uru Hu; OpenEphemeris is an independent calculation service, not affiliated with Jovian Archive.
explore_moon_phase
ChatGPTUse this when the user asks 'what's the moon phase tonight', 'is tonight a full moon', 'show me the moon right now', 'what sign is the Moon in', 'is the Moon void of course' — or has no birth data and wants somewhere to start; it needs no arguments. Returns an interactive Moon dial (inline in Claude and ChatGPT; text summary elsewhere) with: • SVG crescent Moon showing real-time illumination percentage • Phase name and waxing/waning indicator • Current Moon sign with degree • Void-of-Course status with timing details • Lunar age (days in the synodic cycle) and days to the next New and Full Moon • The tightest applying lunar aspects CREDIT COST: 3 credits per call (phase + void-of-course + aspects, 1 each).
explore_natal_chart
ChatGPTUse this when the user asks 'show me my birth chart', 'what's my rising sign', 'my big 3', 'what's my sun, moon and rising', 'what sign is my Moon / Venus / Mars in', 'what does my chart say about my career / love', 'read my chart', or shares birth details and wants to explore them — any natal / birth-chart / astrology-chart request. Returns an interactive chart wheel rendered inline (Claude and ChatGPT; text summary elsewhere) where any planet, house or aspect line can be clicked for interpretation, with switchable house systems. The birthplace can be given as location (a place name — resolved server-side) or as coordinates, together with the birth date and local time and its zone. CREDIT COST: 1 credit per call (+1 to resolve a place name).
explore_transit_timeline
ChatGPTUse this when the user asks 'what transits are coming up for me', 'what's my forecast for the next year', 'when will Saturn hit my chart', 'show my upcoming transits' or 'what's happening astrologically for me in 2027' — a forecast they should SEE. Returns an interactive, date-ordered timeline (inline in Claude and ChatGPT; text summary elsewhere) of exact transit hits grouped by month — transiting planet glyph, the natal point it contacts, the aspect, zodiac position and retrograde markers — each clickable for a focused interpretation. Every hit carries its in-orb window (when the transit starts and ends, and which pass it is when a retrograde repeats it), and transits already in orb at the start are listed with applying/separating. ASPECT ANGLES: 0 = conjunction/return (default), 180 = opposition, 90 = square, 120 = trine, 60 = sextile. EFFICIENCY: searches run faster when transiting_planets and natal_points are given. MAX SPAN: Explorer/PayG 1y, Pro 5y, Startup 10y, Scale 40y (longer = 400). CREDIT COST: 1 + span price: ≤1y 5 (6 total), ≤3y 10, ≤5y 15, ≤10y 25, ≤20y 40, ≤40y 70.
explore_vedic_chart
ChatGPTUse this when the user asks 'show my Vedic chart', 'my Jyotish chart', 'what's my nakshatra', 'my sidereal birth chart', 'my rashi chart' or 'what's my lagna'. Returns an interactive South Indian fixed-sign Rashi grid (inline in Claude and ChatGPT; text summary elsewhere) with sidereal (Lahiri by default) placements, nakshatra with pada, navamsa and the Lagna (Ascendant) rashi; click any rashi cell for its themes and the planets placed there. Birthplace may be a place name (location). CREDIT COST: 3 credits per call (chart + render; +1 to resolve a place name).
human_design_chart
ChatGPTUse this when the Human Design chart is wanted as data — 'give me my HD activations', 'which planets sit in which gates, design and personality', 'what are my variables', 'my Human Design chart as JSON'. Returns Type, Strategy, Authority, Profile, defined and undefined Centers, activated Gates and Channels, Incarnation Cross, and both Personality (birth) and Design (~88° of Sun before birth) planetary positions. CREDIT COST: 2 credits per call. HD is minute-sensitive: a zone-less datetime is rejected, because an hour of error changes the Profile and the Design Sun line. Takes coordinates, not a place name.
location_search
ChatGPTUse this when the user gives a birth city or any place name — 'born in Chicago', 'Portland', 'Mumbai, India' — and a chart needs coordinates and a timezone. Returns display name, region (state/province), latitude, longitude and IANA timezone. With the birth date as date it also returns utcOffsetAtDate, the historically-correct UTC offset for that place on that date; post-1970 dates resolve locally at no extra cost, pre-1970 dates consult the historical overlay for the top match (+1 credit) and return its provenance. The result is flagged ambiguous when several places share the name (e.g. "portland"). A trailing "City, ST" qualifier in the query is honored. CREDIT COST: 1 credit per call.
timezone_resolve
ChatGPTUse this when the user asks 'what timezone is this location in' or 'what was the UTC offset there on that date', or when latitude/longitude are known and the IANA timezone is needed to interpret a local birth time. Takes coordinates, not a place name. Returns the IANA zone and, with date, the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call.
vedic_chart
ChatGPTUse this when the Vedic / Jyotish chart is wanted as data — 'my sidereal placements as JSON', 'nakshatra and pada for every planet as a table', 'my navamsa positions'. Takes coordinates, not a place name. Returns sidereal planet placements in rashis, nakshatras with pada, navamsa placements and bhavas (Whole Sign houses). SUPPORTED AYANAMSA: lahiri (default), fagan_bradley, krishnamurti, raman, yukteshwar CREDIT COST: 1 credit per call.
