Back to Docs

Transit Timeline (Western)

Transit Timeline

POST/api/v1/western/transits/timeline
High plan required

Compute transit-to-natal intervals for Gantt, calendar, and timeline rendering. The default mode covers a single calendar month, andyear_slowextends the window to long-cycle medium and slow bodies across up to 366 days.

Full URL

https://api.freeastroapi.com/api/v1/western/transits/timeline
Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

Timeline Semantics

The endpoint scans beyond the visible month to detect real orb entry and exit, then clips the visible part of the interval with month-specific helper fields.

  • •Intervals can begin before range_start or end after range_end. Keep the real dates for duration math and use the visible day fields for rendering.
  • •month mode is capped to one calendar month per request. year_slow allows a longer long-cycle window up to 366 days, including cross-year ranges.
  • •Use transit_categories to request only fast, medium, slow, or any combination. In year_slow mode, the valid categories are medium and slow.
  • •exact_hits_in_month is the month-clipped subset of exact_datetimes. Use it for visible exact markers without recomputing dates in the frontend.
  • •orb_settings can be layered by aspect, by transit category, or by transit planet. Planet-specific overrides win over category overrides, and category overrides win over global aspect defaults.
  • •Sidereal requests are supported through natal.zodiac_type and natal.sidereal_ayanamsa. These settings affect both the natal reference points and the transit interval calculations.

For a single-date snapshot instead of interval bars, keep using /api/v1/transits/calculate.

Request Parameters

Field
natal.name
Type
string
Required
No
Description
Optional name label for the natal chart owner.
Field
natal.year
Type
integer
Required
Yes
Description
Birth year.
Field
natal.month
Type
integer
Required
Yes
Description
Birth month (1-12).
Field
natal.day
Type
integer
Required
Yes
Description
Birth day.
Field
natal.hour
Type
integer
Required
No
Description
Birth hour. Required for angle-sensitive timelines.
Field
natal.minute
Type
integer
Required
No
Description
Birth minute.
Field
natal.time_known
Type
boolean
Required
No
Description
When false, default natal points exclude angles.
Field
natal.city
Type
string
Required
Yes
Description
Birth city name.
Field
natal.lat
Type
float
Required
Yes
Description
Birth latitude.
Field
natal.lng
Type
float
Required
Yes
Description
Birth longitude.
Field
natal.tz_str
Type
string
Required
No
Description
Birth timezone such as `Europe/Paris` or `AUTO`.
Field
natal.zodiac_type
Type
string
Required
No
Description
tropical (default) or sidereal.
Field
natal.sidereal_ayanamsa
Type
string
Required
No
Description
When zodiac_type is sidereal: lahiri, raman, kp, fagan_bradley, or yukteshwar.
Field
mode
Type
string
Required
No
Description
Timeline mode. Defaults to `month`. Use `year_slow` for a long-cycle window up to 366 days.
Field
range_start
Type
string
Required
Yes
Description
Range start as `YYYY-MM-DD` or full ISO datetime. Date-only values normalize to `00:00:00Z`. `month` mode must stay within a single calendar month; `year_slow` can span multiple months up to 366 days.
Field
range_end
Type
string
Required
Yes
Description
Range end as `YYYY-MM-DD` or full ISO datetime. Date-only values normalize to `23:59:59Z`. `month` mode must stay within the same calendar month as `range_start`; `year_slow` can cross year boundaries as long as the total window is 366 days or less.
Field
include_houses
Type
boolean
Required
No
Description
When true, add a nested `houses` block for each transit with natal-point and transit house context when available.
Field
transit_categories
Type
array[string]
Required
No
Description
Optional category filter. Supported values: `fast`, `medium`, `slow`, or `all`. In `year_slow` mode, use `medium`, `slow`, or both.
Field
transit_planets
Type
array[string]
Required
No
Description
Optional transit planet filter. Supports planets plus `chiron`, `north_node`, `mean_node`, `true_node`, `lilith` (mean Black Moon Lilith), and `true_lilith`. Defaults to the current transit taxonomy excluding the Moon. In `year_slow` mode, the expected long-cycle set includes Jupiter, Saturn, Uranus, Neptune, Pluto, nodes, Chiron, and Lilith variants.
Field
natal_points
Type
array[string]
Required
No
Description
Optional natal point filter. Supports planets, `chiron`, `north_node`, `mean_node`, `true_node`, `lilith`/`mean_lilith`, `true_lilith`, and angle-derived points such as `ascendant`, `midheaven`, `descendant`, `ic`, `vertex`, and `part_of_fortune` when `time_known=true`. Defaults to natal planets plus angles when time is known.
Field
aspect_types
Type
array[string]
Required
No
Description
Optional aspect filter. Defaults to the 5 major aspects: conjunction, square, opposition, trine, and sextile.
Field
orb_settings
Type
object
Required
No
Description
Optional orb override policy. Supports flat per-aspect overrides for backward compatibility, plus nested `by_aspect`, `by_category`, and `by_planet` maps.
Field
orb_settings.by_aspect
Type
object
Required
No
Description
Per-aspect orb overrides, for example `{ "conjunction": 6, "square": 4 }`.
Field
orb_settings.by_category
Type
object
Required
No
Description
Per-category orb overrides. Keys are `fast`, `medium`, or `slow`; each value can define aspect-specific overrides plus `default`, for example `{ "slow": { "default": 3.5 } }`.
Field
orb_settings.by_planet
Type
object
Required
No
Description
Per-transit-planet orb overrides. Keys are transit planets like `saturn`, `jupiter`, or `pluto`; each value can define aspect-specific overrides plus `default`, for example `{ "saturn": { "conjunction": 2, "default": 2.5 } }`.

Response Fields

Field
meta.endpoint
Type
string
Required
n/a
Description
Fixed endpoint identifier: `western_transits_timeline`.
Field
meta.version
Type
string
Required
n/a
Description
Current response version.
Field
meta.range_start
Type
string
Required
n/a
Description
Normalized UTC start timestamp for the requested month.
Field
meta.range_end
Type
string
Required
n/a
Description
Normalized UTC end timestamp for the requested month.
Field
meta.generated_at
Type
string
Required
n/a
Description
UTC generation timestamp.
Field
input.mode
Type
string
Required
n/a
Description
Resolved timeline mode: `month` or `year_slow`.
Field
input.include_houses
Type
boolean
Required
n/a
Description
Echoes whether house data was explicitly requested for this response.
Field
input.transit_categories
Type
array[string]
Required
n/a
Description
Resolved category filter used to build the response.
Field
input.transit_planets
Type
array[string]
Required
n/a
Description
Resolved transit planet set. `mean_lilith` resolves to `lilith`, while `true_lilith`, `mean_node`, and `true_node` remain distinct.
Field
input.natal_points
Type
array[string]
Required
n/a
Description
Resolved natal point set. `mean_lilith` resolves to `lilith`; `vertex` and `part_of_fortune` require `time_known=true`.
Field
input.aspect_types
Type
array[string]
Required
n/a
Description
Resolved aspect set.
Field
transits[].id
Type
string
Required
n/a
Description
Stable intrinsic transit ID. Use this as the frontend dedupe key across months.
Field
transits[].series_key
Type
string
Required
n/a
Description
Stable grouping key like `transit.square.saturn.sun`.
Field
transits[].category
Type
string
Required
n/a
Description
Transit category: `fast`, `medium`, or `slow`.
Field
transits[].transit_planet
Type
string
Required
n/a
Description
Transit planet key.
Field
transits[].natal_point
Type
string
Required
n/a
Description
Natal point key.
Field
transits[].aspect_type
Type
string
Required
n/a
Description
Aspect key.
Field
transits[].label
Type
string
Required
n/a
Description
Human-readable transit label.
Field
transits[].short_symbol_label
Type
string
Required
n/a
Description
Compact glyph label for dense timeline UIs.
Field
transits[].start_datetime
Type
string
Required
n/a
Description
True orb entry datetime in UTC. Can be before the requested month.
Field
transits[].exact_datetimes
Type
array[string]
Required
n/a
Description
All exact hits for the returned interval segment.
Field
transits[].end_datetime
Type
string
Required
n/a
Description
True orb exit datetime in UTC. Can be after the requested month.
Field
transits[].duration_days
Type
number
Required
n/a
Description
Full interval duration in decimal days.
Field
transits[].pass_type
Type
string
Required
n/a
Description
Transit motion state for this interval segment: `direct` or `retrograde`.
Field
transits[].visible_start_day
Type
integer
Required
n/a
Description
1-based day number where the transit bar should start inside the requested month.
Field
transits[].visible_end_day
Type
integer
Required
n/a
Description
1-based day number where the transit bar should end inside the requested month.
Field
transits[].continues_from_previous_month
Type
boolean
Required
n/a
Description
True when the interval started before the requested month.
Field
transits[].continues_to_next_month
Type
boolean
Required
n/a
Description
True when the interval ends after the requested month.
Field
transits[].exact_hits_in_month
Type
array[string]
Required
n/a
Description
Subset of `exact_datetimes` that falls within the requested month.
Field
transits[].row_key
Type
string
Required
n/a
Description
Frontend row grouping key: `<transit>__<aspect>__<natal>`.
Field
transits[].pair_key
Type
string
Required
n/a
Description
Frontend pair grouping key: `<transit>__<natal>`.
Field
transits[].houses.natal_point_house
Type
integer
Required
n/a
Description
Natal house for the natal point in the native's own natal chart house system when birth time is known. Returned only when `include_houses=true`.
Field
transits[].houses.transit_house_at_exact
Type
integer
Required
n/a
Description
Transit planet house, measured against the natal houses, at the first exact hit of the interval when available.
Field
transits[].houses.transit_house_in_month
Type
integer
Required
n/a
Description
Transit planet house, measured against the natal houses, for the requested month slice. Uses an exact hit in the month when available, otherwise a visible-interval probe.

Date Window Rules

Use either YYYY-MM-DD or a full ISO 8601 datetime. month requests must stay inside one calendar month. year_slow requests can span multiple months, including across year boundaries, but must stay at or below 366 days and use medium/slow long-cycle bodies such as Jupiter and Saturn.

2026-03-01 normalizes to 2026-03-01T00:00:00Z.

2026-03-31 normalizes to 2026-03-31T23:59:59Z.

2026-03-15T12:00:00Z keeps the explicit UTC timestamp.

Real Monthly Example

This example is based on a real March 2026 request for Gabriel, born on September 5, 1995 at 20:00 in Paris, filtered to medium and slow transits.

curl -X POST "https://api.freeastroapi.com/api/v1/western/transits/timeline" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "mode": "month",
    "natal": {
        "name": "Gabriel",
        "year": 1995,
        "month": 9,
        "day": 5,
        "hour": 20,
        "minute": 0,
        "time_known": true,
        "city": "Paris",
        "lat": 48.8566,
        "lng": 2.3522,
        "tz_str": "Europe/Paris",
        "zodiac_type": "sidereal",
        "sidereal_ayanamsa": "lahiri"
    },
    "range_start": "2026-03-01",
    "range_end": "2026-03-31",
    "include_houses": true,
    "transit_categories": ["medium", "slow"]
}'

Real Response Example

{
  "meta": {
    "endpoint": "western_transits_timeline",
    "version": "v1",
    "range_start": "2026-03-01T00:00:00Z",
    "range_end": "2026-03-31T23:59:59Z",
    "generated_at": "2026-04-06T12:59:02Z"
  },
  "input": {
    "mode": "month",
    "include_houses": true,
    "transit_categories": ["medium", "slow"],
    "transit_planets": ["jupiter", "saturn", "uranus", "neptune", "pluto", "north_node", "chiron"],
    "natal_points": ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "north_node", "ascendant", "midheaven", "descendant", "ic"],
    "aspect_types": ["conjunction", "square", "opposition", "trine", "sextile"]
  },
  "transits": [
    {
      "id": "transit.opposition.uranus.pluto@2026-02-04T02:22:01Z",
      "series_key": "transit.opposition.uranus.pluto",
      "category": "slow",
      "transit_planet": "uranus",
      "natal_point": "pluto",
      "aspect_type": "opposition",
      "label": "Uranus Opposition Natal Pluto",
      "short_symbol_label": "♅ ☍ ♇",
      "start_datetime": "2026-02-04T02:22:01Z",
      "exact_datetimes": ["2026-03-12T15:56:15Z"],
      "end_datetime": "2026-09-10T17:22:01Z",
      "duration_days": 218.625,
      "pass_type": "direct",
      "visible_start_day": 1,
      "visible_end_day": 31,
      "continues_from_previous_month": true,
      "continues_to_next_month": true,
      "exact_hits_in_month": ["2026-03-12T15:56:15Z"],
      "row_key": "uranus__opposition__pluto",
      "pair_key": "uranus__pluto",
      "houses": {
        "natal_point_house": 4,
        "transit_house_at_exact": 11,
        "transit_house_in_month": 11
      }
    },
    {
      "id": "transit.opposition.north_node.sun@2025-07-23T19:52:30Z",
      "series_key": "transit.opposition.north_node.sun",
      "category": "slow",
      "transit_planet": "north_node",
      "natal_point": "sun",
      "aspect_type": "opposition",
      "label": "North Node Opposition Natal Sun",
      "short_symbol_label": "☊ ☍ ☉",
      "start_datetime": "2025-07-23T19:52:30Z",
      "exact_datetimes": ["2025-12-21T21:49:13Z"],
      "end_datetime": "2026-05-21T23:45:56Z",
      "duration_days": 302.162109,
      "pass_type": "retrograde",
      "visible_start_day": 1,
      "visible_end_day": 31,
      "continues_from_previous_month": true,
      "continues_to_next_month": true,
      "exact_hits_in_month": [],
      "row_key": "north_node__opposition__sun",
      "pair_key": "north_node__sun"
    }
  ]
}

Related Endpoints

Natal Chart

Resolve the natal reference used by transit timelines.

Secondary Progressions

Another timing endpoint with timeline-style output.

Transits Docs Root

Legacy route kept for compatibility. This new page is the dedicated timeline URL.