Traditional Astrology
Sect, essential dignity, the Hermetic lots, antiscia, annual profections, zodiacal releasing, firdaria and solar arc directions — the body of technique that the Hellenistic and medieval sources describe, returned as data.
These are not variations on a natal chart. They are a different way of reading one, and they have one property in common that shapes this whole API: the sources disagree with each other, and they have done so since antiquity. Valens reverses the lots at night; some modern authors do not. Dorotheus gives every triplicity a participating ruler; Ptolemy gives none and hands Mars the watery triangle by day and by night. Two tables of bounds survive and they differ in half the signs.
Most astrology software picks one of each and says nothing. That is precisely why it is not trusted: you cannot see which tradition you have been given.
The rule for this API
Wherever the sources disagree, it is a parameter with a documented default and the source named. Never a silent choice. Every response also echoes what was applied, so two traditions can be set side by side and the difference read off.
What this is and is not
We implement what the sources say. We do not claim it is true. "According to Valens, Anthology Book IV" is a correct statement about this API; "this predicts your career" is not.
Required Module
Everything on this page requires the traditional:calc feature permission, granted by the Traditional Astrology module, which every plan carries. It is not sold separately, and is deliberately not part of the module:calculations bundle.
Two kinds of endpoint
What is a property of a chart — sect, the lots, dignity, antiscia, triplicity — rides along on the natal endpoint as an opt-in include. No second request, no extra ephemeris work: it is arithmetic on a chart that has already been calculated.
What is a timeline gets its own route: profections, zodiacal releasing, firdaria and solar arc directions.
| Route | What |
|---|---|
POST /api/calc/natal with include | Sect, lots, dignities, antiscia, triplicity |
POST /api/calc/profections | Annual, monthly and daily profections |
POST /api/calc/zodiacal-releasing | The releasing tree, with peaks and the loosing of the bond |
POST /api/calc/firdaria | Main periods and sub-periods |
POST /api/calc/solar-arc | Directions to points and to the angles |
Asking for a block is not a breaking change
include is opt-in, so a response you already receive does not change shape when a new block is added to this list. That is why none of this needs an API version — and why adding any of it unconditionally would.
Sect
Whether a chart is diurnal or nocturnal. One comparison, and the whole of traditional astrology hangs off it: which triplicity ruler is in charge, which way round the lots go, which malefic is the difficult one, where the firdaria sequence starts.
curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" },
"include": ["sect"]
}'{
"data": {
"traditional": {
"sect": {
"isDay": true,
"sect": "day",
"method": "altitude",
"degreesFromBoundary": 51.4,
"sunAltitude": 51.4,
"sectLight": "sun",
"beneficOfSect": "jupiter",
"maleficOfSect": "mars",
"methodsDisagree": false
},
"applied": { "sectMethod": "altitude", "horizonAltitude": 0, "...": "..." }
}
}
}The two criteria, honestly
traditional.sectMethod chooses between:
altitude(default) — the Sun's altitude above the horizon, in equatorial coordinates.longitude— the Sun's ecliptic longitude relative to the Ascendant/Descendant axis, which is what most astrology software does because it needs nothing but the Ascendant.
It is often said these disagree around sunrise. With a horizon at exactly 0° they do not, and it is worth being precise about why: the Ascendant is by definition the degree where the ecliptic crosses the horizon, so for a body lying on the ecliptic — which the Sun does, to within a second of arc — the two questions are the same geometry. Anyone who has seen two programs disagree here was looking at two different Ascendants, or at the real difference below.
That real difference is the horizon itself. traditional.horizon moves it:
| Value | Boundary |
|---|---|
geometric (default) | The Sun's centre at altitude zero |
apparent | Visible sunrise — 50′ lower, 34′ of refraction plus 16′ of solar semidiameter |
A chart cast in the half hour before geometric sunrise is a night chart by the strict criterion and a day chart by the visible one, and the tradition has no unanimous answer about which it meant. degreesFromBoundary is in every response so a borderline chart is one you are told about rather than one you have to notice.
Essential dignity
include: ["dignities"] returns, for each of the seven traditional planets, both halves of what the sources distinguish:
Essential — a fact about the degree, nothing to do with the chart: domicile, exaltation, triplicity, bound, face, and the debilities detriment, fall and peregrine. The numeric score is Lilly's weighting (domicile 5, exaltation 4, triplicity 3, bound 2, face 1; detriment −5, fall −4, peregrine −5) — included because the almuten is defined in terms of it, and flagged as what it is: one seventeenth-century author's scale, not a measurement.
Accidental — everything else: the whole-sign and quadrant house, angular/succedent/ cadent, whether the planet is in the house it rejoices in, retrogradation, the solar phase (cazimi within 17′, combust within 8°30′, under the beams within 15°), oriental or occidental, which planets overcome it, and whether it is enclosed by the benefics or the malefics.
{
"pointId": "venus",
"sign": "taurus",
"essential": {
"dignities": ["domicile", "triplicity"],
"debilities": [],
"score": 8,
"rulers": { "domicile": "venus", "triplicity": "venus", "bound": "mercury", "face": "mercury" }
},
"accidental": {
"house": 10, "angularity": "angular", "inJoy": false,
"solarPhase": "free", "orientality": "occidental",
"overcomeBy": ["saturn"], "overcomes": []
}
}Which tables
| Parameter | Values | Default | Source |
|---|---|---|---|
traditional.triplicity | dorotheus, ptolemy | dorotheus | Dorotheus, Carmen I.1 — three rulers per element. Ptolemy, Tetrabiblos I.19 — two, and Mars rules water day and night |
traditional.bounds | egyptian, ptolemaic | egyptian | The Egyptian table is what Valens and Dorotheus use; the Ptolemaic is Tetrabiblos I.21 and Lilly's |
Dorotheus is the default because it is the older table and carries a column the later simplification throws away: a scheme with one fewer ruler cannot be reconstructed from one that has it, so defaulting to the richer table loses nothing.
A quick way to tell which table you are looking at
Aries 13° is in Mercury's bound in the Egyptian table and in Venus's in the Ptolemaic one.
Faces run the Chaldean order from Mars on the first face of Aries — one undisputed table, so no parameter.
The lots
include: ["lots"] returns the seven Hermetic lots as Paulus Alexandrinus lists them (Introductory Matters, ch. 23): Fortune, Spirit, Eros, Necessity, Courage, Victory and Nemesis. Each comes with its sign, its whole-sign and quadrant house, its lord, and where that lord sits — because "the lord of the Lot of Fortune in the eleventh" is the sentence the technique exists to produce.
Fortune day: ASC + Moon − Sun night: ASC + Sun − Moon
Spirit day: ASC + Sun − Moon night: ASC + Moon − Sun
Eros day: ASC + Venus − Spirit night: ASC + Spirit − Venus
Necessity day: ASC + Fortune − Mercury
Courage day: ASC + Fortune − Mars
Victory day: ASC + Jupiter − Spirit
Nemesis day: ASC + Fortune − Saturntraditional.reverseLotsByNight defaults to true — Valens, Anthology III.4, and with him Paulus, Dorotheus and Firmicus. Set it to false to apply the diurnal formula to every chart, the modern convention that follows Ptolemy's silence. There is deliberately no third option: "reverse Fortune but not Spirit" is a transcription error, not a tradition.
What getting this wrong costs
In a night chart the unreversed Fortune does not merely shift — it lands on the exact degree where Spirit belongs. Every reading taken from it is then a reading of the other lot, and nothing in the output says so. formula and reversed are on every lot for this reason.
Use traditional.lots to ask for a subset.
Antiscia
include: ["antiscia"] mirrors every point (and both angles) across the two axes:
- Antiscion — reflected across the solstitial axis, 0° Cancer to 0° Capricorn.
180 − longitude. Two degrees that mark days of equal length. - Contra-antiscion — reflected across the equinoctial axis, 0° Aries to 0° Libra.
360 − longitude.
Contacts are reported from both sides, with a default orb of 1° (traditional.antisciaOrb). The tradition is stricter here than for ordinary aspects, because the whole point of an antiscion is that it is close enough to be a hidden identity rather than a relationship.
Profections
One whole sign per year of life from a natal place. Age 0 is the natal sign itself, age 12 is the natal sign again, and the ruler of the sign arrived at is the Lord of the Year.
curl -X POST "https://api.astroapi.cloud/api/calc/profections" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" },
"from": "ascendant",
"startAge": 35,
"years": 3,
"includeMonths": true
}'The year turns on the solar return
Not on 1 January, and not on the calendar birthday. The Sun returns to its natal degree up to a day either side of the date, and a profection year that starts on the wrong day puts the wrong lord in charge at both ends. Every boundary in the response is a real solar return, which is why years is capped at 30 — each one costs a return to find.
from chooses the place profected: ascendant (default and the standard), moon, sun, fortune or mc. Valens profects several, each answering a different question, so leaving them out would be a choice made silently.
Each year carries twelve monthly profections (includeMonths, on by default) and each month can carry twelve daily ones of about two and a half days (includeDays, off by default — 144 periods per year).
Zodiacal releasing
From Valens, Anthology Book IV. Periods released from the sign of a lot in zodiacal order, each as long as the planetary years of that sign's ruler, subdivided one twelfth at a time for four levels: years, months, roughly two and a half days, roughly five hours.
curl -X POST "https://api.astroapi.cloud/api/calc/zodiacal-releasing" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" },
"from": "spirit",
"levels": 2,
"years": 90
}'Loosing of the bond
When the sequence arrives at Cancer or Capricorn, the next period is not the next sign but the opposite one, after which it carries on in zodiacal order. A sign reached by such a jump does not jump again — otherwise the two would trade the sequence back and forth forever.
Why this matters more than it looks
Leave the rule out and the first two or three decades of a timeline are still correct. It only goes wrong later, all at once, and everything after the first jump is the wrong sign. loosingOfTheBond is true by default and every period says whether it was reached by a jump.
Peaks
The periods that matter are the ones reaching the angles of the lot. Valens measures the angular triad from the Lot of Fortune even when the release runs from Spirit, so peakFrom defaults to fortune; peakSigns says which of the angles counts as the peak, the tenth by default. Every period carries signsFromLot, signsFromPeakLot, angularTriad and peak — the client never has to work it out.
Depth
levels is 1 to 4, default 2. Levels 3 and 4 are only expanded where a period overlaps detailWindow, because the unit shrinks twelvefold per level and a fourth level over a lifetime is tens of thousands of periods. limitReached in the response says when a ceiling stopped the tree from growing further.
Which lot
from is spirit (default) or fortune. Valens releases from Spirit for the course of a life and from Fortune for the body and circumstance: the same mechanism, two techniques.
Firdaria
The Persian system, from Abu Ma'shar and through Bonatti into Latin. Seven main periods of fixed length, each divided into seven sub-periods, the cycle closing after seventy-five years.
The sequence starts with the Sun in a day chart and with the Moon in a night chart. It is the same seven-planet cycle either way — Sun, Venus, Mercury, Moon, Saturn, Jupiter, Mars — rotated to its starting point, which is why there is one order and not two.
| Ruler | Years |
|---|---|
| Sun | 10 |
| Venus | 8 |
| Mercury | 13 |
| Moon | 9 |
| Saturn | 11 |
| Jupiter | 12 |
| Mars | 7 |
| Head of the Dragon | 3 |
| Tail of the Dragon | 2 |
includeNodes defaults to true — the majority reading, and what makes the cycle seventy-five years rather than seventy. subdivideNodes defaults to false, because the sources that give the nodes a period run it whole.
Solar arc directions
Every point in the chart, the angles included, moved forward by the arc the Sun has travelled since birth, then read against the natal positions.
curl -X POST "https://api.astroapi.cloud/api/calc/solar-arc" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" },
"targetDate": "2026-09-12T12:00",
"key": "true",
"orb": 1
}'key | Arc |
|---|---|
true (default) | The arc the Sun actually travelled to the secondary-progressed date — what "solar arc" means without qualification |
naibod | 0.9856262833° per year, the Sun's mean daily motion. Does not depend on the season of birth |
ptolemy | Exactly 1° per year. The oldest key and the crudest |
Directions to the Midheaven and Ascendant are included by default (includeAngles). They are the contacts that date an event most sharply, and the measurement that rectification reads. Each contact carries yearsToExact, signed: positive is still ahead.
The default orb is 1°. A direction moves about a degree a year, so a wider orb stops being a date.
Parameter summary
Everything on which the sources disagree, in one table. All of them live under traditional on any of these requests, except the ones marked as top-level.
| Parameter | Values | Default | Where the disagreement is |
|---|---|---|---|
sectMethod | altitude, longitude | altitude | Which criterion defines "above the horizon" |
horizon | geometric, apparent | geometric | Geometric sunrise or visible sunrise |
reverseLotsByNight | boolean | true | Valens reverses the lots at night; some modern authors do not |
lots | array of lot ids | all seven | — |
bounds | egyptian, ptolemaic | egyptian | Two surviving tables of terms |
triplicity | dorotheus, ptolemy | dorotheus | Three rulers per element, or two |
antisciaOrb | 0–5 | 1 | — |
from (profections, top-level) | ascendant, moon, sun, fortune, mc | ascendant | Valens profects several places |
from (releasing, top-level) | spirit, fortune | spirit | Career and course of life, or body and circumstance |
loosingOfTheBond (top-level) | boolean | true | Everyone applies it; the option exists to reproduce software that does not |
peakFrom (top-level) | fortune, spirit | fortune | Which lot the angular triad is measured from |
peakSigns (top-level) | array 1–12 | [10] | Which angle counts as the peak |
includeNodes (firdaria, top-level) | boolean | true | Some transmissions give the nodes a period, some do not |
subdivideNodes (firdaria, top-level) | boolean | false | — |
key (solar arc, top-level) | true, naibod, ptolemy | true | Three keys, three answers |
What is not here yet
- Fixed stars. A catalogue problem rather than a calculation problem, and planned. Parans and heliacal phases are deliberately out of scope: a paran needs simultaneous passage through angles on the real horizon of the place, and a heliacal phase needs a visibility model with arcus visionis, atmospheric extinction and the star's magnitude. That is its own project and barely verifiable. Better nothing than something that looks approximately like it.
- Primary directions. The one technically heavy technique, and the one with the most ways to be quietly wrong. Planned last, on purpose.
- Interpretation texts. The technique is the product in v1. What a firdaria period means is thirteen languages of content and a separate undertaking.