Skip to content

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.

RouteWhat
POST /api/calc/natal with includeSect, lots, dignities, antiscia, triplicity
POST /api/calc/profectionsAnnual, monthly and daily profections
POST /api/calc/zodiacal-releasingThe releasing tree, with peaks and the loosing of the bond
POST /api/calc/firdariaMain periods and sub-periods
POST /api/calc/solar-arcDirections 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.

bash
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"]
  }'
json
{
  "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:

ValueBoundary
geometric (default)The Sun's centre at altitude zero
apparentVisible 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.

json
{
  "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 ​

ParameterValuesDefaultSource
traditional.triplicitydorotheus, ptolemydorotheusDorotheus, Carmen I.1 — three rulers per element. Ptolemy, Tetrabiblos I.19 — two, and Mars rules water day and night
traditional.boundsegyptian, ptolemaicegyptianThe 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 − Saturn

traditional.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.

bash
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.

bash
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.

RulerYears
Sun10
Venus8
Mercury13
Moon9
Saturn11
Jupiter12
Mars7
Head of the Dragon3
Tail of the Dragon2

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.

bash
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
  }'
keyArc
true (default)The arc the Sun actually travelled to the secondary-progressed date — what "solar arc" means without qualification
naibod0.9856262833° per year, the Sun's mean daily motion. Does not depend on the season of birth
ptolemyExactly 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.

ParameterValuesDefaultWhere the disagreement is
sectMethodaltitude, longitudealtitudeWhich criterion defines "above the horizon"
horizongeometric, apparentgeometricGeometric sunrise or visible sunrise
reverseLotsByNightbooleantrueValens reverses the lots at night; some modern authors do not
lotsarray of lot idsall seven—
boundsegyptian, ptolemaicegyptianTwo surviving tables of terms
triplicitydorotheus, ptolemydorotheusThree rulers per element, or two
antisciaOrb0–51—
from (profections, top-level)ascendant, moon, sun, fortune, mcascendantValens profects several places
from (releasing, top-level)spirit, fortunespiritCareer and course of life, or body and circumstance
loosingOfTheBond (top-level)booleantrueEveryone applies it; the option exists to reproduce software that does not
peakFrom (top-level)fortune, spiritfortuneWhich lot the angular triad is measured from
peakSigns (top-level)array 1–12[10]Which angle counts as the peak
includeNodes (firdaria, top-level)booleantrueSome transmissions give the nodes a period, some do not
subdivideNodes (firdaria, top-level)booleanfalse—
key (solar arc, top-level)true, naibod, ptolemytrueThree 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.

AstroAPI Documentation