AstroAPI

Appearance

Transits ​

Calculate planetary transits and their aspects to a natal chart over a specified time period.

Calculate Transits ​

Calculate transits for a date range:

bash
curl -X POST "https://api.astroapi.cloud/api/calc/transit" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-06-15T14:30",
    "birthLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "transitDateStart": "2024-01-01T00:00",
    "transitDateEnd": "2024-01-31T23:59",
    "transitLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    }
  }'
javascript
const response = await fetch("https://api.astroapi.cloud/api/calc/transit", {
    method: "POST",
    headers: {
        "X-Api-Key": "your-api-key",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        birthDate: "1990-06-15T14:30",
        birthLocation: {
            latitude: 51.5074,
            longitude: -0.1278,
            timezone: "Europe/London"
        },
        transitDateStart: "2024-01-01T00:00",
        transitDateEnd: "2024-01-31T23:59",
        transitLocation: {
            latitude: 51.5074,
            longitude: -0.1278,
            timezone: "Europe/London"
        }
    })
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));
python
import requests

response = requests.post(
    "https://api.astroapi.cloud/api/calc/transit",
    headers={
        "X-Api-Key": "your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "birthDate": "1990-06-15T14:30",
        "birthLocation": {
            "latitude": 51.5074,
            "longitude": -0.1278,
            "timezone": "Europe/London"
        },
        "transitDateStart": "2024-01-01T00:00",
        "transitDateEnd": "2024-01-31T23:59",
        "transitLocation": {
            "latitude": 51.5074,
            "longitude": -0.1278,
            "timezone": "Europe/London"
        }
    }
)

print(response.json())

Parameters ​

ParameterTypeRequiredDescription
birthDatestringYesBirth date/time in YYYY-MM-DDTHH:mm format
birthLocationobjectYesBirth location with latitude, longitude, and timezone
transitDateStartstringYesTransit period start in YYYY-MM-DDTHH:mm format
transitDateEndstringYesTransit period end in YYYY-MM-DDTHH:mm format
transitLocationobjectYesTransit location with latitude, longitude, and timezone
houseSystemstringNoHouse system (default: "placidus")
pointsarrayNoCelestial points to calculate (see Available Points)
orbsobjectNoCustom orb values per aspect type
languagestringNoLanguage code for text content (default: "en")
includeTextbooleanNoInclude interpretation text (default: false)
includeReadableEntitiesbooleanNoInclude human-readable entity titles (default: false)

Location Object ​

json
{
  "latitude": 51.5074,
  "longitude": -0.1278,
  "timezone": "Europe/London"
}

Response ​

The response holds the transit period from two angles: crossings is the timeline, aspects is the interpretation.

  • crossings is nested by natal planet, then transiting planet, and lists every pass through the orb with its start, end, exact moment, closest approach and strength. The timeline and calendar views are built from this.
  • aspects has one entry per transiting planet, aspect and natal planet. The interpretation text is there once, and every pass of the period is listed under occurrences. The top-level orb, strength and duration are those of the strongest pass, so the list sorts by importance as it is.
json
{
  "data": {
    "crossings": {
      "sun": {
        "moon": [
          {
            "aspect": "trine",
            "start": "2026-01-20T03:04:00",
            "end": "2026-01-20T09:41:00",
            "emphasized": { "date": "2026-01-20T06:22:00", "angle": 0.0003 },
            "strength": 72.4
          }
        ]
      }
    },
    "transitHouses": { "...": "..." },
    "aspects": [
      {
        "pointA": "moon",
        "pointB": "sun",
        "aspect": "trine",
        "angle": 120,
        "orb": 0.0003,
        "strength": 72.4,
        "duration": {
          "startDate": "2026-01-20T03:04:00",
          "endDate": "2026-01-20T09:41:00",
          "exactDate": "2026-01-20T06:22:00",
          "totalDays": 0.28,
          "daysToExact": -40.1
        },
        "text": "Transiting Moon trine natal Sun ...",
        "occurrences": [
          { "startDate": "2026-01-20T03:04:00", "endDate": "2026-01-20T09:41:00", "exactDate": "2026-01-20T06:22:00", "totalDays": 0.28, "daysToExact": -40.1, "orb": 0.0003, "strength": 72.4 },
          { "startDate": "2026-02-16T12:15:00", "endDate": "2026-02-16T18:50:00", "exactDate": "2026-02-16T15:32:00", "totalDays": 0.27, "daysToExact": -12.7, "orb": 0.0011, "strength": 71.9 },
          { "startDate": "2026-03-15T20:40:00", "endDate": "2026-03-16T03:10:00", "exactDate": "2026-03-15T23:55:00", "totalDays": 0.27, "daysToExact": 14.6, "orb": 0.0006, "strength": 72.1 }
        ]
      }
    ],
    "charts": {
      "transit": { "title": "Transit Chart (Bi-wheel)", "url": "..." },
      "natal": { "title": "Natal Chart", "url": "..." },
      "event": { "title": "Event Chart", "url": "..." }
    },
    "natalPoints": { "...": "..." },
    "natalHouses": { "...": "..." },
    "transitPoints": { "...": "..." }
  }
}

pointA is the transiting planet and pointB the natal planet. text is only present with includeText: true and the transit:texts module.

Compatibility date 2026-09-03

The grouped aspects shape applies from API version 2026-09-03. On earlier versions, aspects has one entry per pass, each repeating the same text, and no occurrences. A three-month period has the Moon making the same aspect to the same natal planet three or four times, so the flat list was several times longer than the number of distinct interpretations. See API Versioning for how to pin a date.

Custom Orbs ​

Specify custom orb values for different aspect types:

bash
curl -X POST "https://api.astroapi.cloud/api/calc/transit" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-06-15T14:30",
    "birthLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "transitDateStart": "2024-01-01T00:00",
    "transitDateEnd": "2024-01-31T23:59",
    "transitLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "orbs": {
      "conjunction": 3,
      "opposition": 3,
      "trine": 2,
      "square": 2
    }
  }'

With Interpretation Text ​

Include interpretation text with your transit calculations:

bash
curl -X POST "https://api.astroapi.cloud/api/calc/transit" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-06-15T14:30",
    "birthLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "transitDateStart": "2024-01-15T00:00",
    "transitDateEnd": "2024-01-15T23:59",
    "transitLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "includeText": true,
    "language": "en"
  }'

iCal Export ​

Export transit events as an iCal (.ics) file that can be imported into calendar applications like Google Calendar, Apple Calendar, or Outlook.

POST /api/calc/transit/ical ​

bash
curl -X POST "https://api.astroapi.cloud/api/calc/transit/ical" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-06-15T14:30",
    "birthLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    },
    "transitDateStart": "2024-01-01T00:00",
    "transitDateEnd": "2024-03-31T23:59",
    "transitLocation": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    }
  }' --output transits.ics

The response is a text/calendar file with Content-Disposition: attachment; filename="transits.ics".

Parameters ​

The iCal export accepts the same parameters as the standard transit endpoint, plus:

ParameterTypeRequiredDescription
aspectsarrayNoFilter by aspect types (e.g., ["conjunction", "trine"])

TIP

Import the downloaded .ics file into your calendar app to see transit events as calendar entries with descriptions of each aspect.

AstroAPI Documentation

Copyright © 2026 AstroAPI