Skip to content

Western predictive calculations

Predictive Western endpoints derive time-based factors from a stored Western natal chart. All routes require charts:read.

Transits — GET /v1/western/charts/{id}/transits

Transit-to-natal contacts for a single moment.

Query param Type Required Notes
at ISO 8601 datetime yes Must include timezone. 
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.astrolinkers.com/v1/western/charts/$CHART/transits?at=2026-01-01T00:00:00Z"

{
  "natal_chart_id": "019e32b5-...",
  "transit_chart_id": "019e42b1-...",
  "at": "2026-01-01T00:00:00Z",
  "hits": [
    {
      "transit_planet": "jupiter",
      "natal_planet": "sun",
      "aspect": "trine",
      "orb_degrees": 0.742,
      "strength": 0.8939,
      "is_applying": true
    }
  ]
}

Natal targets are treated as stationary, so is_applying reflects the transiting body moving toward or away from exact contact.

Transit windows — GET /v1/western/charts/{id}/transit-windows

Daily-resolution windows where a transit contact stays in orb.

Query param Type Required Notes
starts_at ISO 8601 datetime yes Inclusive start.
ends_at ISO 8601 datetime yes Inclusive end. Must be after starts_at.

Ranges are limited to 400 days per request.

[
  {
    "transit_planet": "saturn",
    "natal_planet": "moon",
    "aspect": "square",
    "starts_at": "2026-02-01T00:00:00Z",
    "ends_at": "2026-02-18T00:00:00Z",
    "exact_at": "2026-02-09T00:00:00Z",
    "min_orb_degrees": 0.104,
    "peak_strength": 0.9851
  }
]

Secondary progressions — GET /v1/western/charts/{id}/secondary-progressions

Secondary progressed chart for a target date. Uses the standard symbolic key: one ephemeris day after birth for each year of life.

Query param Type Required
at ISO 8601 datetime yes 
{
  "natal_chart_id": "019e32b5-...",
  "progressed_date": "1990-07-20T13:15:00Z",
  "positions": [
    {
      "planet": "sun",
      "sign": "cancer",
      "longitude": 118.42,
      "degree_in_sign": 28.42,
      "speed_per_day": 0.953,
      "is_retrograde": false
    }
  ],
  "hits": []
}

Solar arc directions — GET /v1/western/charts/{id}/solar-arc

Solar arc directions use the distance from natal Sun to secondary progressed Sun, then add that arc to each natal position.

Query param Type Required
at ISO 8601 datetime yes 
{
  "natal_chart_id": "019e32b5-...",
  "arc_degrees": 35.8124,
  "directed_positions": [
    {
      "planet": "sun",
      "longitude": 305.5953,
      "sign": "aquarius",
      "degree_in_sign": 5.5953
    }
  ],
  "hits": []
}

Progressed lunation — GET /v1/western/charts/{id}/progressed-lunation

Secondary progressed Sun-Moon phase cycle for a target date.

Query param Type Required
at ISO 8601 datetime yes 
{
  "natal_chart_id": "019e32b5-...",
  "progressed_date": "1990-07-20T13:15:00Z",
  "progressed_sun_longitude": 118.42,
  "progressed_moon_longitude": 224.17,
  "phase_name": "first_quarter",
  "phase_angle": 105.75,
  "phase_index": 2,
  "phase_progress": 0.35,
  "previous_phase_at": "1990-07-16T19:08:00Z",
  "next_phase_at": "1990-07-24T07:44:00Z",
  "cycle_seed": "first_quarter_2"
}

This endpoint is a deterministic lifecycle signal for product UI and LLM grounding. It does not generate interpretation text.

Solar return — GET /v1/western/charts/{id}/solar-return

Solar return chart for a calendar year.

Query param Type Required Notes
year integer yes 1800…2400.
latitude float no Return location latitude. Must be supplied with longitude.
longitude float no Return location longitude. Must be supplied with latitude.
house_system enum no placidus, whole_sign, or equal. Defaults to the natal chart's house system.

Return charts are cast for the moment the transiting Sun returns to its natal longitude. If latitude and longitude are omitted, the natal coordinates are used.

The response includes the selected house_system, the return chart's 12 house cusps in houses[], and two natal overlay arrays:

  • house_overlays[] maps each return house cusp into the natal house wheel and includes stable natal topic labels.
  • planet_overlays[] maps each return planet into both the return house and the natal house it activates.
{
  "natal_chart_id": "019e32b5-...",
  "body": "sun",
  "return_at": "2026-06-15T08:42:00Z",
  "chart_id": "019e42b1-...",
  "house_system": "whole_sign",
  "houses": [{"house": 1, "sign": "leo", "longitude": 132.0}],
  "positions": [{"planet": "sun", "sign": "gemini", "longitude": 84.3}],
  "house_overlays": [
    {
      "return_house": 1,
      "return_house_sign": "leo",
      "return_house_longitude": 132.0,
      "natal_house": 5,
      "natal_topics": ["creativity", "romance", "children"]
    }
  ],
  "planet_overlays": [
    {
      "planet": "sun",
      "return_house": 11,
      "natal_house": 3,
      "natal_topics": ["communication", "siblings", "local_environment"]
    }
  ]
}

Lunar return — GET /v1/western/charts/{id}/lunar-return

Next lunar return chart after a requested moment.

Query param Type Required Notes
starts_at ISO 8601 datetime yes Search anchor.
latitude float no Return location latitude. Must be supplied with longitude.
longitude float no Return location longitude. Must be supplied with latitude.
house_system enum no placidus, whole_sign, or equal. Defaults to the natal chart's house system.

Annual profections — GET /v1/western/charts/{id}/profections

Annual profection house and traditional time lord.

Query param Type Required
at ISO 8601 datetime yes 
{
  "natal_chart_id": "019e32b5-...",
  "age_years": 36,
  "house": 1,
  "sign": "cancer",
  "time_lord": "moon"
}

Profections advance one sign per completed year from the Ascendant sign.

Annual forecast — GET /v1/western/charts/{id}/annual-forecast

Deterministic annual forecast feature summary.

Query param Type Required
year integer yes

Returns the period profection plus the strongest transit windows.

Monthly forecast — GET /v1/western/charts/{id}/monthly-forecast

Deterministic monthly forecast feature summary.

Query param Type Required
year integer yes
month integer yes, 1…12

Zodiacal releasing — GET /v1/western/charts/{id}/zodiacal-releasing

Level-one Hellenistic zodiacal releasing periods from Fortune or Spirit.

Query param Type Required Notes
at ISO 8601 datetime yes Used to mark the current period.
lot "fortune" | "spirit" no, default "fortune" The releasing lot. 
{
  "natal_chart_id": "019e32b5-...",
  "lot": "fortune",
  "lot_longitude": 330.2121,
  "lot_sign": "pisces",
  "periods": [
    {
      "sign": "pisces",
      "ruler": "jupiter",
      "starts_at": "1984-12-21T11:20:00Z",
      "ends_at": "1996-12-21T08:28:00Z",
      "years": 12,
      "is_current": false
    }
  ]
}

Fortune and Spirit use the standard day/night formula reversal. Day/night is determined by whether the Sun is above the horizon.

Advanced zodiacal releasing — GET /v1/western/charts/{id}/zodiacal-releasing/advanced

Nested zodiacal releasing through L1-L4, preserving the original L1 endpoint for clients that only need a simple sequence.

Query param Type Required Notes
at ISO 8601 datetime yes Used to mark current periods.
lot "fortune" | "spirit" no, default "fortune" The releasing lot.
levels integer no, default 4 1…4. 
{
  "natal_chart_id": "019e32b5-...",
  "lot": "fortune",
  "lot_longitude": 330.2121,
  "lot_sign": "pisces",
  "levels": [1, 2, 3, 4],
  "periods": [
    {
      "level": 1,
      "sign": "pisces",
      "ruler": "jupiter",
      "starts_at": "1984-12-21T11:20:00Z",
      "ends_at": "1996-12-21T08:28:00Z",
      "years": 12.0,
      "is_current": false,
      "is_peak": true,
      "is_loosening_of_bond": false,
      "parent_sign": null
    }
  ]
}

is_peak marks angular signs from the releasing lot. is_loosening_of_bond marks the seventh sign in each level sequence.