Astrology Transits API

Calculate a complete natal chart, a chart for one requested transit instant, and aspects from each transiting body to each natal body.

Tropical, geocentric longitude is the default. This endpoint returns geometry; it does not score, rank, or narrate the result.

Endpoint

POST https://api.astroapi.io/api/astro/transits

Request contract

  • birth.date, birth.time, birth.lat, and birth.lon are required.
  • birth.timezone is an IANA timezone and defaults to UTC.
  • transitDate is required in YYYY-MM-DD form.
  • transitTime defaults to 12:00.
  • Top-level timezone controls the transit instant and defaults to birth.timezone, then UTC.
  • The public date window is 1900-01-01 through 2050-12-31.

Example request

{
  "birth": {
    "date": "1990-01-01",
    "time": "12:00",
    "timezone": "UTC",
    "lat": 40.7128,
    "lon": -74.006
  },
  "transitDate": "2025-01-01",
  "transitTime": "12:00",
  "timezone": "UTC"
}

Response contract

The Node gateway preserves the historical outer transits envelope. Inside it, natal_chart and transit_chart use the normal chart schema; aspects contains transit-to-natal relationships. This example is abbreviated from the engine regression fixture. 

{
  "type": "transits",
  "input": {
    "birth": { "date": "1990-01-01", "time": "12:00", "timezone": "UTC", "lat": 40.7128, "lon": -74.006 },
    "transitDate": "2025-01-01",
    "transitTime": "12:00",
    "timezone": "UTC"
  },
  "transits": {
    "status": "ok",
    "zodiac": "tropical",
    "ayanamsa": null,
    "natal_chart": {
      "status": "ok",
      "planets": {
        "Sun": { "lon": 280.8143, "sign": "Capricorn" },
        "Moon": { "lon": 333.2677, "sign": "Pisces" }
      },
      "houses": { "ascendant": 274.6427, "mc": 208.9108 }
    },
    "transit_chart": {
      "status": "ok",
      "planets": {
        "Sun": { "lon": 281.3234, "sign": "Capricorn" },
        "Moon": { "lon": 300.6611, "sign": "Aquarius" }
      },
      "houses": { "ascendant": 275.1339, "mc": 209.4507 }
    },
    "aspects": [
      {
        "transit": "Sun",
        "natal": "Sun",
        "type": "conjunction",
        "exact_angle": 0,
        "distance": 0.5091,
        "orb": 0.5091
      }
    ]
  }
}

Aspect fields

  • transit is the body in the requested transit chart.
  • natal is the body in the submitted birth chart.
  • distance is their smallest angular separation.
  • exact_angle is the exact geometry of the matched aspect.
  • orb is the absolute difference between those two values.

Sidereal mode

Send "zodiac": "sidereal" and optionally select lahiri, raman, or krishnamurti. See the sidereal transit guide.

Errors and quota

  • 400 invalid fields, timezone, coordinate, zodiac, ayanamsa, or date range
  • 401 missing or invalid key; 429 quota or edge rate limit
  • 502 engine unavailable; 503 concurrency limit; 504 timeout
  • Requests admitted past authentication and quota checks are logged as billable attempts, including validation and engine failures.