Transits (Western)

POST/api/v1/transits/calculate

Calculate planetary transits for a specific date and compare them to a natal chart. Returns current planetary positions and aspects formed between transiting and natal planets.

By default, the response includes interpretation blocks and the transit body setsun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, true_node, chiron, lilith. Disable interpretations with "interpretation": {"enable": false}.

Untimed births are supported via natal.time_known=false. In that mode, the natal side behaves like the Natal endpoint: houses and angles are omitted, and natal planet house placements are not returned.

Full URL

https://api.freeastroapi.com/api/v1/transits/calculate

How Transit Calculations Work

Transits compare the current sky (or any specified date) with a person's natal chart.

•(T) indicates a transiting planet (current position)
•(N) indicates a natal planet (birth position)
•Aspects between (T) and (N) planets reveal current life themes

Request Parameters

Parameter	Type	Required	Description
natal.name	string	No	Name of the person (default: User)
natal.year	integer	Yes	Natal birth year
natal.month	integer	Yes	Natal birth month (1-12)
natal.day	integer	Yes	Natal birth day
natal.time_known	boolean	No	Default: true. Set false for unknown birth time. In untimed mode, natal houses and angles are omitted.
natal.hour	integer	No	Natal birth hour (0-23). Required when natal.time_known=true. Ignored structurally when natal.time_known=false.
natal.minute	integer	No	Natal birth minute. Required when natal.time_known=true. Ignored structurally when natal.time_known=false.
natal.lat	float	Yes	Natal birth latitude
natal.lng	float	Yes	Natal birth longitude
current_city	string	Yes	Current location city name
current_lat	float	No	Current location latitude (optional if city provided)
current_lng	float	No	Current location longitude (optional if city provided)
transit_date	string	No	Transit date in ISO format (default: now)
tz_str	string	No	Timezone for transit location (default: AUTO)
orb_settings	object	No	Optional per-aspect orb overrides, e.g. { Conjunction: 8, Trine: 6 }
interpretation	object	No	Interpretations are enabled by default. Pass { enable: false } to disable interpretation blocks.

📅 Transit Date Format

Use ISO 8601 format: YYYY-MM-DDTHH:MM

Examples:

2025-01-15T12:00 - January 15, 2025 at noon

2025-06-21T00:00 - June 21, 2025 at midnight

Sample Code

curl -X POST "https://api.freeastroapi.com/api/v1/transits/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "natal": {
        "name": "John Doe",
        "city": "New York",
        "year": 1990,
        "month": 5,
        "day": 15,
        "time_known": false,
        "hour": 10,
        "minute": 30,
        "lat": 40.7128,
        "lng": -74.006,
        "tz_str": "AUTO"
    },
    "transit_date": "2025-01-15T12:00",
    "current_city": "Paris",
    "current_lat": 48.8566,
    "current_lng": 2.3522,
    "tz_str": "AUTO",
    "orb_settings": {
        "Conjunction": 8.0,
        "Opposition": 8.0,
        "Trine": 6.0,
        "Square": 6.0,
        "Sextile": 4.0
    }
}'

Response Data

{
  "transit_date": "2025-01-15",
  "transit_time": "12:00:00",
  "mode": "transit_to_natal",
  "location": {
    "city": "Paris",
    "lat": 48.8566,
    "lng": 2.3522,
    "timezone": "Europe/Paris"
  },
  
  "natal_planets": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": "Tau",
      "pos": 24.72,
      "abs_pos": 54.72,
      "house": 9
    }
    // ...
  ],
  
  "transit_planets": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": "Cap",
      "pos": 25.12,
      "abs_pos": 295.12,
      "house": 5,
      "retrograde": false
    }
    // ...
  ],

  // Default set includes: sun, moon, mercury, venus, mars, jupiter,
  // saturn, uranus, neptune, pluto, true_node, chiron, lilith
  
  "aspects": [
    {
      "p1": "Sun (N)",
      "p2": "Sun (T)",
      "between": { "natal": "sun", "transit": "sun" },
      "type": "Trine",
      "orb": 0.4,
      "deg": 120.0,
      "is_major": true,
      "is_applying": true
    }
    // ...
  ],
  
  "aspects_summary": {
    "total": 18,
    "major": 12,
    "minor": 6,
    "applying": 8,
    "separating": 10,
    "by_type": { "Trine": 4, "Square": 3 }
  },

  "interpretation": {
    "metadata": { "found_count": 12, "missing_keys": [] },
    "sections": {
      "core_self": [
        {
          "key": "aspect.sun.trine.sun",
          "title": "Sun Trine Sun (Transit)",
          "body": "A period of vital harmony where your current path aligns perfectly with your core essence..."
        }
      ]
      // ... mind, love_relating, work_path, etc.
    },
    "index": {
      "aspects": [
        {
          "p1": "sun",
          "p2": "sun",
          "type": "trine",
          "title": "Sun Trine Sun (Transit)",
          "content": "..."
        }
      ]
    }
  }
}

Related Endpoints

Natal Chart

Calculate the natal chart first

SVG Synastry Chart

Generate a relationship bi-wheel chart for two people

BaZi Flow

Chinese astrology timing analysis