Help

This page is here to show you around ZodiaLux itself first: where to click, what each tab does, and how to get a chart on screen. Once you know your way around the app, the cheat sheet at the bottom offers a plain-English primer on the astrology behind the charts, for anyone who wants a refresher on planets, points, houses, and signs.

Getting Started

ZodiaLux is a birth chart and astrology calculator. Enter any date, time, and place, and it draws the wheel, tables, and aspects for that moment, whether that is your own birth chart or any other point in time.

Look at the Spacetime Navigator on the right (or tap the date/time button at the bottom on mobile).
Type a Year, pick a Month from the dropdown, and type a Day.
Set the Hour, Minute, and Second in 24-hour time.
Type a city into the Location field and pick a match from the dropdown list, or press Enter to use the top match.
Click Calculate Chart to draw the wheel for that date, time, and place.
Click Save Chart to keep it. Sign in if prompted, give it a Name, and click Save.

Tips

Saved charts show up under My Charts in the Chart Library on the right-hand panel, and on the Charts tab.
You do not need an account to calculate a chart, only to save one.

Transits (Home)

The Transits tab is the ZodiaLux home page. It opens showing the current sky, live, and refreshes every five minutes until you start moving the date around.

Open the Transits tab to see the current sky right now.
Use the Spacetime Navigator on the right (or the drawer on mobile) to change the date, time, or location, then click Calculate Chart.
Click · Now at any time to jump straight back to the live moment.
Switch between Wheel and Tables view using the View toggle in the left sidebar.

Tips

By default you see the ten planets (Sun through Pluto) plus the North Node, Ascendant, and Midheaven. Toggle more bodies, including the asteroids, South Node, Lilith, Descendant, and IC, in the Bodies section of the left sidebar.
On mobile, tap Planets in the bottom dock to open the same body toggles in a popover.
The live transits view stops auto-refreshing as soon as you change the date yourself.

Charts

The Charts tab is your chart library: saved charts, an interactive wheel, and tables for a closer read of any chart.

Open the Charts tab to see your chart library, split into My Charts and Site Charts.
Search by name or tag, then click Load on a chart, or click its card, to open it.
Hover a planet in the wheel to highlight it; click it to open its detail panel with sign, house, dignity, and aspects.
Switch to Tables view to read the Planet Table, House Table, and Aspect Grid together.
Hover any cell in the Aspect Grid to see the exact aspect and orb for that pair.
Use the Spacetime Navigator to change the date, time, or place, then click Calculate Chart to recompute.

Tips

Delete a saved chart from the library with the trash icon. This cannot be undone.
Add a second chart with Add Chart to see a biwheel, or open the Compare section below for progressions, returns, and solar arc.

Compare & Biwheels

Compare mode shows two charts together: overlaid as a biwheel, side by side, or as an aspect grid comparing them body by body. ZodiaLux can also calculate progressions, returns, and solar arc directions: three classic techniques for seeing how a chart unfolds over time. Find them under Add Chart, then Supplementary, while in Compare mode.

Click Add Chart in the Spacetime Navigator (the right-hand panel on the Transits page, or the Chart A panel in Compare Mode) and choose Saved chart or Transits to bring in a second chart.
The wheel switches to a biwheel automatically: your first chart sits on the inner ring, the second on the outer ring. Click the ⇅ swap button to flip which ring each chart occupies.
Toggle Multi and Dual above the wheel. Multi overlays both charts in one wheel; Dual shows them as two separate circles side by side.
For a full split-screen layout with two independent Spacetime Navigators, open the command palette (Ctrl+K, or Cmd+K on Mac) and choose Compare Mode.
Switch to Tables view to see the Interwheel Aspect Grid: one chart's bodies run across the top, the other's run down the side, and each cell is the aspect between them.
On mobile, the Compare Dock at the bottom shows one control bar per chart. Use the ▲ and ▼ arrows to reorder rings, the clock or arrow icons (or Edit for a saved chart) to change its date, and × to remove it.
In Compare mode, click Add Chart and choose Supplementary.
Pick a type: Progression, Return, or Solar Arc.
For a Return, choose which body to return: Sun, Moon, Mercury, Venus, Mars, Jupiter, or Saturn.
Set the year, or the year, month, and day for a Return, then click Create chart.
Use the step arrows next to the supplementary chart to move to the next or previous progression year, return, or solar arc date.

Tips

Progression (secondary progression): each day after your birth stands for one year of life. A progressed chart shows how your natal planets have symbolically moved by now.
Return: the exact moment a planet returns to the same zodiac degree it held at your birth. A Solar Return happens close to your birthday each year; other returns follow that body's own cycle, roughly monthly for the Moon and about every 29 years for Saturn.
Solar Arc: shifts every planet in your chart forward by the same number of degrees the Sun has progressed since birth, a technique astrologers use for timing key life events.

Notes

Notes let you jot thoughts about a specific chart and read them back later, right from the wheel or from a full list.

Click Notes in the top bar to open the notes panel. Sign in if prompted.
Load or save a chart first. Every note attaches to a saved chart, so the panel shows a prompt to save one until it has a chart to attach to.
Type in the composer at the top of the panel and click Add note.
Use shorthand for glyphs as you type: mer becomes ☿, sat becomes ♄, ari becomes ♈, then press Tab to insert the glyph.
Open the Notes tab in the top navigation to see every note across all your charts in one list.
Search notes by text, or use the chart dropdown to filter down to one chart at a time.

Tips

Click a note to edit it in place.
Clear an active chart filter with the × on its filter chip.

Ephemeris

An ephemeris is a table showing where every planet sits on each date. Use it to scan weeks or months of sky movement at a glance.

Open the Ephemeris tab in the top navigation.
Pick a Start date, then choose a Span (30 days up to 1 year) and a Step (Daily, 3-day, or Weekly) for the spacing between rows.
Choose Local or Zulu for the time reference. In Local mode, type a city into the location field so positions match that place's clock; Zulu shows positions in UTC.
Pick Noon or Midnight as the time of day each row is calculated for.
Toggle which planets appear as columns using the pill buttons above the table.
Read across a row: each column shows a planet's sign and degree in the format D°MM′SS″.

Tips

Retrograde motion shows a small gold retrograde symbol next to the degree, explained in the legend under the table.
Retrograde motion also shows up as the degree numbers decreasing from one day to the next.

Settings

Settings controls what shows by default every time you open a chart, from house system to which planets appear.

Open the Settings tab in the top navigation.
Click Use my current chart view to pull in whatever is showing on the Transits page right now, as a starting point.
Pick a House System. See the House Systems section below for what each one means.
Choose True or Mean for the Lunar Node. True tracks the Moon's actual, wobbling orbital path and matches most modern software; Mean is a smoothed, traditional default that ignores that wobble.
Set a Default Location and Timezone so new charts start there instead of blank.
Choose which planets, asteroids, and points show by default under Shown Bodies, along with your default Orb Preset, Glyph Size, and Default Theme.
Pick a Wheel Style for single charts and for double (biwheel) charts. French style places the zodiac ring on the inside with planets radiating outward.

Tips

Wheel style and Lunar Node changes apply immediately. Other settings save automatically and show a Saved confirmation.

House Systems

A house system is the method ZodiaLux uses to slice the sky into 12 houses. Different traditions slice it differently. If you do not know which to pick, Whole Sign and Placidus are the two most common starting points. You can switch systems any time in Settings and the chart updates instantly.

Whole Sign

Sign-based

The oldest system, standard in Hellenistic and much traditional astrology, and popular again today. No division math at all: the sign your Ascendant falls in becomes the entire 1st house, the next sign is the 2nd house, and so on. Works at every latitude.

Equal

Sign-based

Every house is exactly 30 degrees, measured from the exact degree of your Ascendant. Simple, predictable, and works at every latitude.

Porphyry

Space-based

An ancient space-based system. It takes the four angles (Ascendant, IC, Descendant, Midheaven) as fixed walls and splits each quarter of the sky into three equal houses.

Placidus

Time-based

The default in most modern Western astrology. Time-based: it divides houses by how long each degree of the zodiac takes to rise from the horizon up to the midheaven. Its math distorts near the poles, so ZodiaLux automatically switches to Porphyry above 66 degrees latitude.

Koch

Time-based

Another time-based system, sometimes called the Birthplace system. Popular in German-speaking countries and in some modern psychological astrology. Like Placidus, it struggles at extreme latitudes.

Regiomontanus

Space-based

A medieval space-based system that divides the celestial equator into twelve equal arcs. The classic choice for horary astrology (chart-of-the-question work).

Campanus

Space-based

Space-based: divides the prime vertical (the great circle running from due east overhead to due west) into equal arcs. Favored by some medieval astrologers and some modern locational work.

Time-based systems answer 'how long does this part of the sky take to rise', space-based systems answer 'how big is this slice of space', and sign-based systems just count whole signs.

Export & Sharing

Export turns your chart into a PDF or image file you can save, print, or share.

Open a chart, then click Export above the wheel.
Choose a format: PDF for a printable document with tables and notes, or Image (PNG) for the wheel alone.
For a PDF, toggle Include data tables and Include notes section on or off.
If you include notes, choose Written notes to print what you have already saved, or Blank lines to print a page of ruled lines to write on by hand.
Click Download to save the file.

Tips

Visitors who are not signed in cannot export. Free and paid accounts both can.
Free exports carry a small Generated with ZodiaLux footer. Paid accounts get white-label exports with no ZodiaLux branding.

Importing & Exporting Your Library

Separate from exporting a single chart as a PDF: this moves your whole chart library in and out of ZodiaLux, either as a backup you can restore from or as a file another astrology program can read.

Go to the Charts tab and find Import and Export above the chart list.
To export, tick some charts first if you only want those, then click Export and choose Selected charts or Your whole library.
Pick a format. ZodiaLux file (.json) is the one that restores everything. AAF and CSV are for handing your birth data to other programs.
Leave Include notes on if this is a backup. Turn it off if you are giving the file to someone else, because your note text is inside it.
Click Download.
To import, click Import and drop a file in. ZodiaLux reads its own .json files, AAF files from astro.com, .SFcht files from Solar Fire or Astro Gold, and CSV chart lists.
You get a preview first: how many charts are ready, which ones have warnings, and which were skipped and why.
Check the preview, then confirm. Everything from one import is tagged imported- plus the date, so a bad import is one tag to undo.

Tips

Only the .json format is a real backup. AAF, CSV and .SFcht can carry a name, date, time and place and nothing else — no tags, no notes, no house system, and no link between a derived chart and the chart it came from.
.SFcht is import only. It is a binary format with no published specification, so ZodiaLux can read one but will not write one — a file we generated could be subtly wrong in a way nobody could check.
If an imported chart's time zone disagrees with the one ZodiaLux works out from the coordinates, the preview says so on that row. The chart still uses the coordinates. It is worth reading those warnings: they usually mean the original program had the wrong zone.
Derived charts (progressions, returns, solar arc) are left out of AAF and CSV exports on purpose, and the export tells you when it has done so. They export normally in the .json format.
* The CSV export includes a header row naming each column. That is what makes it open cleanly in a spreadsheet, but some astrology programs expect the data to start on the first line — delete the header row before importing it elsewhere if the program complains.
Time zones are always worked out from the coordinates, so an offset written in an imported file is checked against ours and reported if the two disagree, rather than being used.
A chart with no birth time imports at 12:00 noon and is flagged. A chart with a place name but no coordinates is never guessed at — the wrong town would change both the houses and the time zone.

Astrology Cheat Sheet

New to astrology? These tables give you just enough vocabulary to read your chart. Each entry is a starting point, not a rulebook.

Planets

The planets and what each one represents
Planet	Part of you	Keywords	Rules
Sun	Your core self and identity	vitality, purpose, confidence, creativity	Leo; self-expression, leadership, the father figure
Moon	Your emotions and instincts	feelings, habits, moods, memory, comfort	Cancer; home life, nurturing, the mother figure
Mercury	Your mind and voice	thinking, communication, learning, wit	Gemini and Virgo; speech, writing, commerce, siblings, short trips
Venus	What you love and value	affection, beauty, harmony, pleasure	Taurus and Libra; relationships, money, art, attraction
Mars	Your drive and desire	energy, courage, anger, ambition	Aries (traditionally also Scorpio); action, competition, conflict, passion
Jupiter	Your growth and beliefs	optimism, luck, expansion, wisdom	Sagittarius (traditionally also Pisces); opportunity, long journeys, higher learning, faith
Saturn	Your discipline and limits	responsibility, patience, structure, mastery	Capricorn (traditionally also Aquarius); career, time, authority, life lessons
Uranus	Your individuality and need for freedom	change, rebellion, innovation, surprise	Aquarius (modern); technology, breakthroughs, sudden events
Neptune	Your dreams and imagination	intuition, spirituality, illusion, compassion	Pisces (modern); dreams, art, mysticism, escapism
Pluto	Your capacity for transformation	intensity, power, rebirth, depth	Scorpio (modern); the hidden, endings and renewals, shared power

Points & Angles

Nodes and angles and what each represents
Point	Represents	Keywords
North Node	The direction of growth in this life, the unfamiliar territory worth stretching toward	destiny, development, life lessons
South Node	Where you come from, the skills and habits that feel automatic	innate gifts, comfort zone, old patterns, release
Ascendant (ASC)	The self you show the world, first impressions, your approach to life	outward style, appearance, the mask
Descendant (DSC)	What you seek in one-on-one partners, the qualities you attract	partnership, projection, the other
Midheaven (MC)	Your public life and direction	career, reputation, calling, legacy
IC (Imum Coeli)	Your roots and private foundation	home, family origins, the inner base

Houses

Houses are the 'where' of a chart: which area of life a planet acts in. Body correspondences are the traditional astrological associations, listed for students of classical technique.

The twelve houses and their life areas
House	Life Areas	Body	Keywords
1	Self, appearance, beginnings	head, face	identity, vitality, first impressions
2	Money, possessions, values	neck, throat	income, security, self-worth
3	Communication, siblings, short trips	arms, hands, lungs	learning, writing, neighbors
4	Home, family, roots	chest, stomach	foundations, parents, real estate
5	Creativity, romance, children	heart, upper back	pleasure, play, self-expression
6	Work, health, daily routines	digestive system	service, habits, pets
7	Partnerships and marriage	kidneys, lower back	commitment, contracts, open rivals
8	Shared resources, intimacy, transformation	reproductive organs	inheritance, debt, taxes, rebirth
9	Travel, higher education, beliefs	hips, thighs, liver	philosophy, publishing, law
10	Career and public standing	knees, bones, skin	achievement, reputation, authority
11	Friends, groups, hopes	ankles, calves, circulation	community, causes, future goals
12	Solitude, the unconscious, endings	feet, lymphatic system	retreat, hidden things, spirituality

Signs

The twelve zodiac signs and their qualities
Sign	Element / Modality	Ruler	Keywords	Affinity
Aries	Fire / Cardinal	Mars	bold, direct, pioneering, impatient	self, fresh starts
Taurus	Earth / Fixed	Venus	steady, sensual, patient, stubborn	money, possessions
Gemini	Air / Mutable	Mercury	curious, quick, versatile, scattered	communication, learning
Cancer	Water / Cardinal	Moon	nurturing, protective, intuitive, moody	home, family
Leo	Fire / Fixed	Sun	warm, dramatic, generous, proud	creativity, romance
Virgo	Earth / Mutable	Mercury	precise, helpful, analytical, critical	work, health
Libra	Air / Cardinal	Venus	charming, fair, diplomatic, indecisive	partnerships, marriage
Scorpio	Water / Fixed	Pluto (traditionally Mars)	intense, private, magnetic, transformative	intimacy, shared resources
Sagittarius	Fire / Mutable	Jupiter	adventurous, honest, philosophical, blunt	travel, beliefs
Capricorn	Earth / Cardinal	Saturn	ambitious, disciplined, practical, reserved	career, achievement
Aquarius	Air / Fixed	Uranus (traditionally Saturn)	original, independent, humanitarian, detached	friends, community
Pisces	Water / Mutable	Neptune (traditionally Jupiter)	dreamy, empathic, artistic, escapist	spirituality, the unconscious

Hermetic Lots (Arabic Parts)

A Hermetic Lot (also called an Arabic Part) is not a body — nothing sits there physically. A Lot is a distance measured between two points, then projected out from the Ascendant, the way you might pace off the gap between two landmarks and then walk that same distance starting from your own front door.

SECT decides which formula to use. A chart born with the Sun above the horizon is a `day` chart; born with the Sun below the horizon, it is a `night` chart. Every Lot formula reverses between the two, which is why the same birth data can place the Part of Fortune somewhere completely different depending on whether the day or night version was used.

The Part of Fortune shows this most clearly. By day: Ascendant + Moon − Sun. By night: Ascendant + Sun − Moon. Flipping sect does not nudge the answer a little, it reflects it through the Ascendant to a different point that can still look perfectly plausible.

Read a formula as zodiac longitudes added and subtracted, then wrapped back into 0–360°. ASC + Moon − Sun means: take the Ascendant's longitude, add the Moon's, subtract the Sun's. Note that only Fortune and Spirit are built from the luminaries — the other five are built from Fortune or Spirit rather than from the Sun and Moon directly, which is the step most often got wrong.

The seven Hermetic Lots, what each represents, and its day and night formula
	Lot	Represents	Formula
⊗	Part of Fortune	Body, circumstance and livelihood — the Moon's distance from the Sun, cast from the Ascendant.	Day ASC + Moon − SunNight ASC + Sun − Moon
SP	Part of Spirit	Mind, action and what you set out to do. Fortune's mirror.	Day ASC + Sun − MoonNight ASC + Moon − Sun
ER	Part of Eros	Desire and what draws you — measured through Venus and the Lot of Spirit.	Day ASC + Venus − SpiritNight ASC + Spirit − Venus
NC	Part of Necessity	Constraint and things outside your control — measured through Mercury and Fortune.	Day ASC + Fortune − MercuryNight ASC + Mercury − Fortune
CG	Part of Courage	Boldness and the capacity to act — measured through Mars and Fortune.	Day ASC + Fortune − MarsNight ASC + Mars − Fortune
VC	Part of Victory	Success and where effort is rewarded — measured through Jupiter and Spirit.	Day ASC + Jupiter − SpiritNight ASC + Spirit − Jupiter
NM	Part of Nemesis	Limits, endings and what is retributive — measured through Saturn and Fortune.	Day ASC + Saturn − FortuneNight ASC + Fortune − Saturn

Lots are built from zodiac longitudes, so they follow whichever zodiac frame the rest of the chart is using. Calculate a chart in sidereal mode and the Lots come out sidereal too, automatically.

Techniques & Extra Bodies

Techniques and body groups that do not fit a table. Each of these is a plain description of what the thing is, not a full lesson in how to practise it.

Zodiacal Releasing

A Hellenistic timing technique, described by Vettius Valens, that turns a chart into a dated timeline of chapters. You start from the sign of a Lot and walk the zodiac in order, giving each sign a stretch of time taken from the lesser years of its ruling planet: Aries 15, Taurus 8, Gemini 20, Cancer 25, Leo 19, Virgo 20, Libra 8, Scorpio 15, Sagittarius 12, Capricorn 27, Aquarius 30, Pisces 12.

Which Lot you release from decides what the timeline is about. Releasing from the Part of Fortune describes the body, circumstances and livelihood — things that happen to you. Releasing from the Part of Spirit describes action, career and what you set out to do.

The same sequence repeats at four nested levels, each in smaller units, so a decades-long chapter contains years, which contain months, which contain days. Reading it is a matter of seeing which level's boundaries line up: when a new period starts at two or three levels at once, that is a bigger turn than a single sub-period changing.

Two conventions decide every date on the screen, and real software disagrees about both. A releasing year here is 360 days, not a calendar year, which is what reproduces the published worked examples. And the loosing of the bond — the jump out of sequence to the opposite sign, traditionally a turning point — fires after a full twelve-sign lap returns to the parent's own sign, roughly 17.6 years in.

Where to find it: Extras → Zodiacal Releasing. Pick a saved chart, choose Fortune or Spirit, and read down the levels.

Planetary Hours

An older way of dividing the day than the clock. Take the time from sunrise to sunset and split it into twelve equal parts: those are the twelve hours of the day. Do the same from sunset to the next sunrise for the twelve hours of the night. Because daylight is longer in summer, a daytime planetary hour in June is well over sixty minutes and a nighttime one is well under. Only at the equinoxes do the two match the clock.

Each hour is ruled by a planet, running in Chaldean order — Saturn, Jupiter, Mars, Sun, Venus, Mercury, Moon, slowest to fastest — and repeating around. The first hour after sunrise belongs to the ruler of the weekday, which is where the names of the days come from: Sunday starts on the Sun's hour, Monday on the Moon's, Saturday on Saturn's.

The traditional use is electional: start something in the hour of the planet that governs it. Mercury's hour for a letter or a negotiation, Venus's for anything social, the Moon's for travel and small beginnings, Saturn's for what you want slow and durable.

Where to find it: Extras → Planetary Hours. It shows the current hour and the full day and night table for your location.

Void of Course Moon

The Moon is void of course when it will make no further major aspect to a planet before it leaves the sign it is in. It is a gap: the Moon has finished its business in that sign and has not yet started the next one. Voids run anywhere from a few minutes to well over a day.

The traditional reading is that nothing will come of it. Matters begun during a void tend to fizzle out, go nowhere, or turn out to be less than they looked. The practical version most astrologers use is milder: it is a poor window for launching, signing and deciding, and a fine one for rest, routine and anything already under way.

Which planets count changes the answer, so ZodiaLux offers both conventions. The Hellenistic rule uses only the seven classical planets, so a final aspect to Uranus, Neptune or Pluto does not close a void. The modern rule includes the outer planets, which makes voids shorter and rarer. If two apps disagree about tonight's void, this is almost always why.

Where to find it: Extras → Void-of-Course Moon. Scan a date range, switch between the modern and Hellenistic rules, and open any entry as a chart.

Asteroids and Extra Bodies

Beyond the planets, the ephemeris can also place a set of smaller bodies. The four classical asteroids are Ceres, Pallas, Juno and Vesta, all discovered in the early 1800s in the belt between Mars and Jupiter. Chiron is not an asteroid but a centaur, orbiting between Saturn and Uranus. Lilith, as normally used, is not a body at all — it is the Moon's apogee, the empty focus of the lunar orbit.

Modern practice reads them as specialists rather than as full voices. Ceres for nurture, food and cycles of loss and return. Pallas for pattern recognition, craft and strategy. Juno for partnership and its terms. Vesta for devotion and what you keep sacred. Chiron for the durable wound and the skill that grows out of tending it. Lilith for what has been exiled or refused.

They are switched off by default here, and that is deliberate rather than an oversight. A chart with every optional body enabled reads as noise, and the traditional framework the rest of the app is built on — sect, rulership, Lots, releasing — has nothing to say about a body discovered in 1801. Turn them on when you have a specific question that needs one, not as a standing default.

Where to find it: Settings → Shown Bodies. Turn on the Asteroids group there and its toggles appear in the left bar alongside the planets, in the wheel, the position table and the aspect grid.

Historic Dates

ZodiaLux calculates charts back to 500 BC, verified to within about a degree of Swiss Ephemeris. Entering a date that far back works differently than a modern birthday, mostly because of two calendars quietly disagreeing with each other.

The Gregorian calendar (the one on your wall) did not exist before 1582 — it started on 1582-10-15. Historians quoting an earlier date, 15 March 44 BC for Caesar's assassination, for example, are quoting the JULIAN calendar, the one actually in use at the time. ZodiaLux calculates in the proleptic Gregorian calendar internally (Gregorian rules projected backward), the same convention nearly every astronomy library uses, then shows you the Julian-calendar equivalent underneath any date before 1582-10-15, clearly labelled, so you can match what a history book says exactly.

Years before 1 AD use astronomical numbering: there is a year 0, which is what historians call 1 BC. So 500 BC is stored internally as year -499. You never have to do that math yourself — type 500 and switch the toggle to BC, and ZodiaLux converts it for you.

Positions at 500 BC land within about a degree of Swiss Ephemeris, the professional standard. The main source of uncertainty that far back isn't the math, it's Delta-T: the slow, irregular drift in Earth's own rotation rate, which by antiquity carries a real historical uncertainty of a minute or more. That is still an excellent chart for historical and research work, just not one to read to the arcsecond.

Pluto is the one exception. Its position formula is only accurate from 1885 to 2099 — outside that window it can be dozens of degrees off, so ZodiaLux flags it with a warning wherever a chart lands outside that range, rather than quietly showing a wrong placement.

If you're trying to pin down or double-check a date from an ancient source, these are solid, stable starting points:

US Naval Observatory — Julian Date Converter — Converts between calendar dates and Julian Day numbers, and handles both the Julian and Gregorian calendars explicitly — useful for checking a historic date by hand.
NASA Eclipse Web Site (Fred Espenak) — NASA's long-running eclipse reference site: the Five Millennium Canon of solar and lunar eclipses, and the Delta-T (Earth-rotation drift) background behind the historical timing uncertainty mentioned above — a good independent check if a historic chart's date is anchored to a documented eclipse.

The Wizard

The Wizard (its name is Z) is a chat assistant that answers WHEN and WHERE questions about the sky with real astronomical calculations — the same Swiss-verified engine behind the ZodiaLux charts. Ask it when Saturn leaves Aries, when the Moon is void of course this week, what planetary hour it is right now, or for transits to any of your saved charts. Every date and position in its answers comes from a live calculation, never from the AI's memory.

It is a calculator, not an oracle: it finds exact moments and positions for your criteria. Analysis, meaning, and predictions are deliberately outside its scope — you bring the astrology, it brings the astronomy.

What you need

Two things: a ZodiaLux plan that includes the Wizard, and an AI key from a provider of your choice. ZodiaLux does the astronomy; your AI does the conversation. Your key stays in your browser — it is never sent to ZodiaLux — and your provider bills you directly for what the chat uses.

Cost reality check: the Wizard works great on each provider's cheapest models, and a typical question costs a fraction of a cent. A few dollars of credit lasts a long time. You do not need an expensive model — finding setups is tool work, not deep reasoning.

Getting an AI key

Pick ONE provider below. If you are not sure, use OpenRouter — one account covers every major model family, so you can switch models later without a new key.

OpenRouter (easiest — one key, every model)

Keys: openrouter.ai → Settings → Keys

One account gives you models from Google, OpenAI, Anthropic, Meta, DeepSeek, and more, with pay-as-you-go pricing. Create an account, add a few dollars of credit under Settings → Credits, then create a key. In the connect screen, pick the OpenAI-compatible option — the OpenRouter address is pre-filled.

Good budget models: google/gemini-2.5-flash, openai/gpt-4o-mini, anthropic/claude-haiku-4.5

OpenAI

Keys: platform.openai.com → API keys

Note this is the developer platform, not a ChatGPT Plus subscription — they are separate accounts and separate billing. Add a small amount of credit under Billing, then create a key.

Good budget models: gpt-4o-mini

Anthropic (Claude)

Keys: console.anthropic.com → Settings → API keys

Same idea: the developer console is separate from a Claude.ai subscription. Add credit under Plans & Billing, then create a key.

Good budget models: claude-haiku-4.5

Google (Gemini)

Keys: aistudio.google.com → Get API key

Sign in with any Google account and create a key in AI Studio — Google currently offers a free usage tier that is plenty for the Wizard.

Good budget models: gemini-2.5-flash

Treat any AI key like a password: paste it only into the ZodiaLux connect screen, and if you ever suspect it leaked, revoke it on the provider's key page.

Connecting

Open the Wizard tab in the top navigation (or Account → Wizard on desktop, where the same connect card lives). Then:

Pick your provider. For OpenRouter, choose the OpenAI-compatible option — the address is pre-filled.
Paste your key and press Test — it checks the key directly with your provider.
Pick a model from the list. The recommended budget models are marked; cheap is fine.
Choose where the key lives: this session only (gone when the tab closes) or remember on this device (encrypted in this browser, so you get a one-click reconnect next visit). Either way it never touches our servers.
Connect and ask your first question.

Two settings that make it much better

1. Home location. Fill in your default location in Settings. The Wizard then knows where you are — planetary hours, void-of-course times, and rising signs come back for your sky without it asking. Name another place in any question ("planetary hours for Denver tomorrow") to override it.

2. Your own chart. Under Account → Wizard, pick which saved chart is you. Then "my transits", "my Saturn return", and "when does Jupiter cross my Ascendant" go straight to your chart — no birth-data questions.

Privacy note: when you ask about a saved chart, its name and birth data are sent to the AI provider you connected — the same trust boundary as the rest of the chat. Saved charts are never available to API keys, only to your signed-in session.

What to ask it

Positions and charts: where is Mars right now? cast a chart for March 15, 1990, 3:45pm in Riga.
Ingresses and retrogrades: when does Saturn leave Aries? when is Mercury retrograde next, and in what signs?
Moon work: when is the next full moon and in what sign? is the Moon void of course today? list this week's voids.
Planetary hours: what planetary hour is it? when is the Venus hour on Friday?
Your charts: my transits right now. where is Saturn for Leandra? compare my chart with Jordan's.
Exact hits: when exactly does transiting Pluto square my natal Sun? next Jupiter–Saturn conjunction?
Elections: find me days next month with the Moon in Taurus, Venus direct, during a Venus hour, avoiding voids.
Eclipses and returns: eclipses in 2027? when is my solar return this year — cast that chart.

Every exact moment in an answer carries a clickable date — click it and the chart wheel jumps to that moment (with your chart loaded, it adds a transit ring instead, keeping your natal chart in place).

What it will not do

No interpretation, advice, or predictions — it calculates; the meaning is your craft.
Chiron and asteroids are not computed by the engine yet; it will say so and offer the nearest supported point.
Tropical by default; ask for a sidereal chart (Lahiri or Fagan-Bradley) on positions and full charts. Ingress, retrograde, aspect-time, and other date-search questions stay tropical for now.
Usage is metered in compute units (your daily balance shows on Account → API Keys); very large scans may ask to be split.

Troubleshooting

It is not doing something this page says it does: Disconnect and reconnect. The Wizard's instructions are fetched when you connect, so an old chat keeps old behavior until you reconnect.
Provider errors (401, quota, model not found): that is between your key and your provider — check the key is active and the account has credit. The Test button on the connect screen tells you quickly.
It asked where you are: set your home location in Settings, then reconnect.
Slow or rambling answers: try one of the recommended budget models — they are usually faster AND better at tool work than bigger ones.
Something else off? Use the Feedback button — real questions from real astrologers are exactly what shapes the Wizard.

Calculation API

Precision astronomical calculations — positions, charts, transits, ingresses, retrogrades, eclipses, electional scans — over plain HTTPS, from your own scripts, spreadsheets, or custom agents. Everything is computed by the same Swiss-verified engine that powers the ZodiaLux charts. Calculation only: the API returns data, never interpretation.

You need a ZodiaLux API key (zlx_live_…), created on your Account page under API Keys. Keys are available on plans that include calculation API access.

Base URL

https://www.zodialux.com/api/v1

Always call the www host exactly as written above. The bare domain zodialux.com answers with a redirect, and HTTP clients (curl, fetch, requests, …) drop the Authorization header when they follow a redirect to a different host — so a perfectly valid key gets a 401 UNAUTHORIZED. If your first call fails with 401, check the host before anything else.

Authentication

Send your key as a bearer token on every request:

Authorization: Bearer zlx_live_YOUR_KEY

Keys are shown once at creation and stored hashed. Revoking a key on the Account page takes effect immediately.

Quickstart

One endpoint does all the work: pick a tool, pass its params.

curl -s https://www.zodialux.com/api/v1/calc \
  -H "Authorization: Bearer zlx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_planet_position",
    "params": {
      "body": "Sun",
      "datetime": "2026-07-05T12:00",
      "timezone": "America/Denver"
    }
  }'

A successful response:

{
  "ok": true,
  "tool": "get_planet_position",
  "params": { "body": "Sun", "datetime": "2026-07-05T12:00", "timezone": "America/Denver" },
  "result": {
    "body": "Sun",
    "longitude": 103.7363,
    "sign": "Cancer",
    "degreeInSign": 13.7363,
    "speed": 0.9534,
    "retrograde": false
  },
  "usage": { "units_charged": 1, "units_remaining_today": 499, "cached": false }
}

Request & response shape

POST https://www.zodialux.com/api/v1/calc with a JSON body of { "tool": "<name>", "params": { … } }. Every response — success or error — is JSON with an ok boolean.

Field	Meaning
`ok`	true on success; false on any error.
`tool`	The tool that ran.
`params`	The validated params the engine actually used (defaults filled in).
`result`	The calculation result. Shape varies per tool; field names are self-describing.
`usage.units_charged`	Compute units this call cost (see the table below).
`usage.units_remaining_today`	Units left in your daily allowance (or free trial).
`usage.cached`	true when the result came from the deterministic result cache. Cached repeats still charge full units — identical questions have identical answers, so cache your own results client-side.

Tools & unit costs

Sixteen tools are available to API keys. Scan tools charge by window length — windows are also capped by your plan (default 100 years; the Moon caps sky-to-sky scans at 1 year).

Tool	What it returns	Units
`get_planet_position`	Zodiac position of one body at one moment: longitude, sign, degree, daily motion, retrograde flag.	1
`compute_natal_chart`	Full chart for a moment and place: positions, 12 house cusps, Ascendant, Midheaven, aspects.	2
`compute_transits`	Aspects from the sky at one moment to a natal chart, with natal house placements when birth coordinates are given.	2
`compute_progressions`	Secondary-progressed chart (day-for-a-year) and its aspects to natal bodies.	2
`compute_synastry`	Cross-chart aspects between two natal charts.	2
`compute_composite_chart`	Midpoint composite chart for two people (both birth locations required).	2
`find_returns`	Exact moments a body returns to its natal longitude — solar, lunar, Saturn returns, etc.	2 + 1 per 5 years of window
`get_moon_phase`	Phase, illuminated fraction, Moon's sign, and the next four quarter events with each quarter's sign.	1
`find_eclipses`	Lunar and solar eclipses in a range, with the eclipsed luminary's sign and longitude.	2 + 1 per 5 years
`find_retrograde_periods`	A planet's station-retrograde and station-direct moments in a range.	2 + 1 per 5 years
`find_sign_ingresses`	Every sign boundary a body crosses in a range; retrograde re-entries flagged.	2 + 1 per 5 years
`find_mundane_aspects`	Exact moments two transiting bodies perfect an aspect to each other (the heaviest scan).	3 + 1 per 2 years
`scan_election_windows`	Composite electional scan: day scores, rising-sign blocks, house-ruler condition, ruler-aspect criteria.	days mode: 3 + 1 per 7 days · blocks mode: 5 + 1 per day
`find_aspect_times`	Exact moments a transiting body perfects an aspect to a fixed natal position or degree.	2 + 1 per 5 years
`get_planetary_hours`	All 24 planetary hours for a local date at a location: sunrise, sunset, day ruler, each hour's ruler and exact bounds.	2
`find_voc_moon`	Void-of-course Moon periods in a window: last Ptolemaic aspect, sign ingress, duration.	4 + 1 per 30 days

Machine-readable schemas: GET https://www.zodialux.com/api/v1/agent-config (same bearer auth) returns the full JSON-Schema parameter definitions for every tool, plus the system prompt the ZodiaLux Wizard itself uses — ready to hand to an LLM. Add ?provider=openai, ?provider=anthropic, or ?provider=gemini to get the tool list pre-translated into that provider's function-calling format.

Conventions

Input	Convention
Datetimes	Local wall time like `"1990-03-15T15:45"` plus an IANA `timezone` param (e.g. `"America/Denver"`), historical DST handled. A datetime carrying `Z` or a UTC offset is used as-is. Bare dates are fine for search windows.
Coordinates	Decimal degrees, north and east positive. Resolve place names to coordinates yourself — the API takes numbers, not city names.
Bodies	Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, plus `NorthNode`, `SouthNode`, and `Lilith` where a tool's schema allows points. Chiron and asteroids are not computed.
Zodiac	Tropical by default. `get_planet_position`, `compute_natal_chart`, `compute_progressions`, `compute_synastry`, and `compute_composite_chart` also accept `zodiac`: `sidereal-lahiri` or `sidereal-fagan-bradley`. Scan tools (ingresses, retrogrades, returns, aspect times, eclipses, mundane aspects, elections, planetary hours, void-of-course) are tropical only for now.
House systems	`whole-sign` (default), `equal`, `porphyry`, `placidus` on chart tools.

Quotas & rate limits

Usage is metered in compute units. Your plan sets a daily allowance (default 500 units/day on paid plans; free accounts get a one-time 50-unit trial) and a burst limit of 30 units per minute. Your live remaining balance is on the Account → API Keys page and in every response's usage block.

One big scan is always possible: a request larger than the whole burst limit (e.g. a 100-year mundane scan at 53 units) is admitted when the current minute's bucket is empty. Its units still land in the bucket, so follow-ups in the same minute wait — that guards against runaway loops without blocking legitimate large scans.

Over any limit, you get HTTP 429:

{
  "ok": false,
  "error": "RATE_LIMITED",
  "reason": "burst",
  "units_remaining_today": 447,
  "retry_after_seconds": 12
}

Saved charts are in-app only

The ZodiaLux Wizard can read the signed-in user's saved chart library via list_saved_charts / get_saved_chart and saved_chart params on the natal-input tools. Those are not available to API keys — any request referencing them returns 403 IN_APP_ONLY. This is deliberate: a leaked key must never expose birth data. Pass explicit birth datetimes and coordinates instead.

Errors

Error responses are { "ok": false, "error": "<CODE>", … }, often with a human-readable detail. Errors are answers — if you feed this API to an LLM agent, return error bodies to the model verbatim; they are written to be relayed.

Status	Code	Meaning
400	`BAD_JSON`	The request body is not valid JSON.
400	`UNKNOWN_TOOL`	The tool name is not one of the tools listed on this page.
401	`UNAUTHORIZED`	Missing, invalid, or revoked key. If your key is definitely right, confirm you are calling the www host — the bare domain redirects and your HTTP client silently drops the Authorization header when it follows.
403	`CALC_API_DISABLED`	The calculation API is switched off site-wide (maintenance). Try again later.
403	`TIER_NO_CALC`	Your ZodiaLux plan does not include calculation API access.
403	`IN_APP_ONLY`	The request referenced saved charts, which API keys cannot access (see Saved charts below).
422	`PARAM_INVALID`	Params failed validation — the detail field says which parameter and why (including scan windows over your plan's year cap).
422	`CALC_ERROR`	The engine rejected the computation — the detail field explains (e.g. an out-of-order date range, polar-day planetary hours).
429	`RATE_LIMITED`	Over quota. The reason field is burst (per-minute), daily (units/day), or trial (free trial exhausted); retry_after_seconds says when to retry.
500	`QUOTA_CHECK_FAILED`	Transient server-side failure — safe to retry once after a pause.

Questions, gaps, or a tool you wish existed? Use the Feedback button anywhere in the app — the API grows in the same direction the Wizard does.

Help

Getting Started

Tips

Transits (Home)

Tips

Charts

Tips

Compare & Biwheels

Tips

Notes

Tips

Ephemeris

Tips

Settings

Tips

House Systems

Whole Sign

Equal

Porphyry

Placidus

Koch

Regiomontanus

Campanus

Export & Sharing

Tips

Importing & Exporting Your Library

Tips

Account & Tiers

Tips

Astrology Cheat Sheet

Planets

Points & Angles

Houses

Signs

Hermetic Lots (Arabic Parts)

Techniques & Extra Bodies

Zodiacal Releasing

Planetary Hours

Void of Course Moon

Asteroids and Extra Bodies

Historic Dates

The Wizard

What you need

Getting an AI key

OpenRouter (easiest — one key, every model)

OpenAI

Anthropic (Claude)

Google (Gemini)

Connecting

Two settings that make it much better

What to ask it

What it will not do

Troubleshooting

Calculation API

Base URL

Authentication

Quickstart

Request & response shape

Tools & unit costs

Conventions

Quotas & rate limits

Saved charts are in-app only

Errors