Transits to a natal chart
get_transit_dataCalculate transiting planets and their aspects to natal points at a given date and time against a birth chart.
Instructions
Call this when someone asks what the sky holds at one moment, now or at a given date and time, against a natal chart: which planets are transiting and which natal points they aspect at that moment. Why: the natal chart and the sky come from the configured engine with fixed settings, so the same input always gives the same numbers. With ENGINE=stub they are placeholders, and the text starts with a PLACEHOLDER line. Inputs: birth_date and birth_time give the birth moment in the local time of the birth place, with place, or with latitude, longitude and timezone. house_system names the natal house system. ayanamsa sets the zodiac of both the natal chart and the sky. harmonic sets the harmonic of both. bodies limits the transiting bodies, and so the midpoints made of them; the natal chart is always whole. transit_date and transit_time give the moment of the sky, with transit_timezone for its zone; leave out both for the sky now. Returns: the transiting bodies with sign, degree, minute and retrograde flag; the aspects, ranked by orb for the default reading and by strength for the others, the 15 tightest unless aspect_limit says otherwise, with the total and a truncated flag; and the sky moment, the birth moment, the house system and the harmonic. Reading: aspects is "major" (default) or "all" (17 vibrational aspects). A point pairing (T to N) takes each aspect's own transit orb; any pairing with a midpoint takes the classic midpoint orb. include lists the pairings, in any order: "points" (default: transiting bodies to natal points, T to N), "to_natal_midpoints" (to natal midpoints, T to Nm), "transit_midpoints" (midpoints of transiting bodies to natal points, Tm to N) and "midpoint_to_midpoint" (transit midpoints to natal midpoints, Tm to Nm). Every row names its pairing, the points or midpoint pairs involved, orb, strength and phase (applying, separating or unknown). The default reading keeps its keys, order, orb and strength, and only a row whose phase is unknown changes its applying (false) and text ("phase unknown"); any other reading ranks by strength. Every row has the same keys. min_strength keeps the aspects at or above a strength from 0 to 1, and aspect_limit sets how many to list, with 0 for all. Leave out transit_date and transit_time for the sky now. With harmonic above 1, the natal chart and the sky are both multiplied by the harmonic (longitude times harmonic, mod 360), and every longitude returned is that harmonic chart's. Input ayanamsa sets the zodiac for both the natal chart and the sky: tropical by default, or lahiri, fagan_bradley, raman or krishnamurti for sidereal longitudes; a sidereal result names the ayanamsa in meta. Gives positions and facts only, with no interpretation.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| place | No | Birth place to look up, as a name like 'Austin, TX', or one of these shorthands, which stand alone with no region or country: 'NYC', 'New York', 'LA', 'L.A.', 'SF', 'San Fran', 'DC', 'Philly', 'Vegas', 'Peking' or 'Saigon'. Give this or latitude, longitude and timezone, not both. Anything else must be a place name in the GeoNames table, or latitude, longitude and time zone given directly. | |
| bodies | No | Transiting bodies to return, such as Sun and Moo. The midpoints of transiting bodies (Tm) are made from these only; the natal chart is always whole. Codes: Sun, Moo (Moon), Mer (Mercury), Ven (Venus), Mar (Mars), Jup (Jupiter), Sat (Saturn), Ura (Uranus), Nep (Neptune), Plu (Pluto), Chi (Chiron), Nor (Mean North Node, North Node), Cer (Ceres), Pal (Pallas), Jun (Juno), Ves (Vesta), Eri (Eris), Hau (Haumea), Mak (Makemake), Sed (Sedna). Leave out for all of them. | |
| aspects | No | Which aspects to read. "major" (default) reads the five major aspects. "all" reads the 17 vibrational aspects, such as semisquare, quincunx, quintile, septile and novile. The orb depends on the pairing: a point pairing (T to N) takes the transit orb of the aspect's own harmonic, 2 degrees for harmonics 1 to 4 and 1 degree above; any pairing with a midpoint takes the classic midpoint orb, 1.5 degrees for conjunction and opposition and 1.5 × 2 ÷ harmonic for the others. Every row names its pairing, the rows of the default reading too. A row whose phase is unknown reads "phase unknown" and is never applying. The aspect names results use, with other names people use and the angle (no input takes an aspect name): "major" has conjunction (conj, 0°), opposition (opp, 180°), trine (tri, 120°), square (sqr, quartile, 90°), sextile (sex, 60°); "all" adds quintile (qtl, 72°), biquintile (bi-quintile, 144°), septile (sep, 51°26′), biseptile (bi-septile, 102°51′), triseptile (tri-septile, 154°17′), semisquare (semi-square, octile, 45°), sesquiquadrate (sesquisquare, sesqui-square, trioctile, 135°), novile (nonile, 40°), binovile (bi-novile, 80°), quadnovile (quadri-novile, 160°), semisextile (semi-sextile, 30°), quincunx (inconjunct, 150°). | major |
| include | No | Which pairings to read, as a list, in any order: rows are ranked together whatever the order. "points" (default) reads transiting bodies to natal points (T to N). "to_natal_midpoints" reads transiting bodies to natal midpoints (T to Nm). "transit_midpoints" reads midpoints of pairs of transiting bodies to natal points (Tm to N). "midpoint_to_midpoint" reads transit midpoints to natal midpoints (Tm to Nm). Each value gives its own rows, named by pairing. Repeating a value is refused. | |
| ayanamsa | No | Zodiac for the positions: tropical, lahiri, fagan_bradley, raman, krishnamurti. Leave out for tropical. A sidereal value such as lahiri gives sidereal longitudes, with the ayanamsa subtracted from the tropical ones. Pass the value even when a person uses another name for it: tropical is also called Western or sayana; lahiri is also called Lahiri, Chitra Paksha or Indian national ayanamsa; fagan_bradley is also called Fagan-Bradley, Fagan/Bradley or Western sidereal; raman is also called Raman or B. V. Raman; krishnamurti is also called Krishnamurti, KP or K.P.. | tropical |
| harmonic | No | Harmonic to read the chart and the sky in: 1 is the ordinary transit. Above 1, the natal chart and the sky are both multiplied by it (longitude times harmonic, mod 360) before the aspects are read. | |
| latitude | No | Birth latitude in signed decimal degrees, north positive, for example 30.2672. Give with longitude and timezone instead of place. | |
| timezone | No | IANA time zone name for the birth time, such as America/Chicago, America/New_York, America/Los_Angeles, or Europe/London. Give with latitude and longitude instead of place. | |
| longitude | No | Birth longitude in signed decimal degrees, east positive, for example -97.7431. Give with latitude and timezone instead of place. | |
| birth_date | Yes | Birth date in the local calendar of the birth place, as YYYY-MM-DD, for example 1990-06-15. | |
| birth_time | Yes | Birth clock time in the local time of the birth place, 24-hour HH:MM, for example 19:30. | |
| aspect_limit | No | How many aspects to list. The default reading ranks by orb, tightest first; the others rank by strength, to two places, with equal strengths in pairing order. Leave out for 15. 0 lists every aspect. The result always gives the total and whether the list was cut. | |
| house_system | No | House system that sets the house cusps: one of placidus, koch, equal, campanus, regiomontanus, porphyry, whole_sign. Leave out for placidus. Pass the value even when a person uses another name for it: placidus is also called Placidus or Plac; koch is also called Koch, birthplace houses or GOH; equal is also called Equal house or equal from the Ascendant; campanus is also called Campanus or Camp; regiomontanus is also called Regiomontanus or Regio; porphyry is also called Porphyry or Porph; whole_sign is also called Whole Sign, whole-sign houses, sign houses or WSH. | placidus |
| min_strength | No | Keep only the aspects whose strength is at least this, from 0 to 1: 1 at exact and 0 at the edge of the orb. Leave out or 0 keeps every aspect inside its orb. | |
| transit_date | No | Date of the sky to read, as YYYY-MM-DD in transit_timezone, for example 2000-06-15. Give with transit_time, or leave both out for the sky now. | |
| transit_time | No | Clock time of the sky to read, 24-hour HH:MM in transit_timezone, for example 12:00. Give with transit_date, or leave both out for the sky now. | |
| transit_timezone | No | IANA time zone name for transit_date and transit_time, such as America/New_York. Leave out for UT. Give only with transit_date and transit_time. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sky | Yes | The transiting bodies in object-code order. With harmonic above 1 these are the harmonic chart's longitudes. | |
| meta | Yes | Settings and provenance behind the numbers. | |
| aspects | Yes | Aspects between transiting points and natal points, or their midpoints, as the request chose them. | |
| missing | Yes | Object codes the engine did not compute, for the sky or the natal chart. Empty when all were computed. | |
| headline | Yes | The transiting Sun and Moon positions as plain text. Only the bodies in the sky appear. |