Retrograde Periods
Calculate retrograde periods for planets within a specified date range, including pre-retrograde shadow and post-retrograde shadow periods.
Required Module
Requires the retrograde:calc module.
Calculate Retrograde Periods
bash
curl -X POST "https://api.astroapi.cloud/api/calc/retrograde" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-12-31",
"points": ["mercury", "venus", "mars"]
}'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | Start date in YYYY-MM-DD format |
endDate | string | Yes | End date in YYYY-MM-DD format |
points | array | No | Planets to calculate retrograde periods for (see defaults below) |
Default Points
If points is not specified, retrograde periods are calculated for all standard outer and inner planets:
mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, chiron
Date Range
Longer date ranges will include more retrograde periods but may take slightly longer to calculate. There is no strict limit on the date range, but ranges of one or two years are typical.
Response
json
{
"data": {
"dateRange": {
"startDate": "2024-01-01",
"endDate": "2024-12-31"
},
"periodsByPoint": {
"mercury": [
{
"retrogradeStation": {
"date": "2024-04-01T15:14:00Z",
"longitude": 27.3,
"sign": "aries",
"degreesInSign": 27.3
},
"directStation": {
"date": "2024-04-25T08:54:00Z",
"longitude": 15.6,
"sign": "aries",
"degreesInSign": 15.6
},
"durationDays": 24,
"signsTraversed": ["aries"],
"preRetrogradeShadow": {
"startDate": "2024-03-18T00:00:00Z",
"endDate": "2024-04-01T15:14:00Z",
"durationDays": 14
},
"postRetrogradeShadow": {
"startDate": "2024-04-25T08:54:00Z",
"endDate": "2024-05-13T00:00:00Z",
"durationDays": 18
}
}
],
"mars": [
{
"retrogradeStation": {
"date": "2024-12-06T09:33:00Z",
"longitude": 86.0,
"sign": "gemini",
"degreesInSign": 6.0
},
"directStation": {
"date": "2025-02-23T22:00:00Z",
"longitude": 47.2,
"sign": "cancer",
"degreesInSign": 17.2
},
"durationDays": 79,
"signsTraversed": ["gemini", "cancer"],
"preRetrogradeShadow": {
"startDate": "2024-10-26T00:00:00Z",
"endDate": "2024-12-06T09:33:00Z",
"durationDays": 41
},
"postRetrogradeShadow": {
"startDate": "2025-02-23T22:00:00Z",
"endDate": "2025-05-01T00:00:00Z",
"durationDays": 66
}
}
]
},
"periods": [
{
"point": "mercury",
"retrogradeStation": {
"date": "2024-04-01T15:14:00Z",
"longitude": 27.3,
"sign": "aries",
"degreesInSign": 27.3
},
"directStation": {
"date": "2024-04-25T08:54:00Z",
"longitude": 15.6,
"sign": "aries",
"degreesInSign": 15.6
},
"durationDays": 24,
"signsTraversed": ["aries"],
"preRetrogradeShadow": {
"startDate": "2024-03-18T00:00:00Z",
"endDate": "2024-04-01T15:14:00Z",
"durationDays": 14
},
"postRetrogradeShadow": {
"startDate": "2024-04-25T08:54:00Z",
"endDate": "2024-05-13T00:00:00Z",
"durationDays": 18
}
}
]
}
}Response Fields
| Field | Type | Description |
|---|---|---|
dateRange | object | The start and end dates of the requested range |
periodsByPoint | object | Retrograde periods grouped by planet name |
periods | array | All retrograde periods in chronological order |
RetrogradePeriod Object
| Field | Type | Description |
|---|---|---|
retrogradeStation | object | Data for when the planet stations retrograde |
directStation | object | Data for when the planet stations direct |
durationDays | number | Length of the retrograde period in days |
signsTraversed | array | Zodiac signs the planet moves through while retrograde |
preRetrogradeShadow | object | Shadow period before the retrograde begins |
postRetrogradeShadow | object | Shadow period after the planet goes direct |
Station Object
| Field | Type | Description |
|---|---|---|
date | string | UTC timestamp of the station |
longitude | number | Ecliptic longitude (0–360) at the station |
sign | string | Zodiac sign at the station |
degreesInSign | number | Degree within the sign (0–30) |
Shadow Period Object
| Field | Type | Description |
|---|---|---|
startDate | string | UTC start of the shadow period |
endDate | string | UTC end of the shadow period |
durationDays | number | Length of the shadow period in days |
Shadow Periods Explained
Each retrograde has two shadow periods:
- Pre-retrograde shadow: Begins when the planet first reaches the degree where it will eventually go direct. The planet "previews" the territory it will later revisit.
- Post-retrograde shadow: Ends when the planet returns to the degree where it first stationed retrograde. The planet is finishing its review of the retrograde zone.
Planning with Shadows
Many astrologers advise caution not just during the retrograde itself but also during both shadow periods. The full retrograde cycle — pre-shadow, retrograde, post-shadow — is the complete period of review for that planet's themes.
Typical Retrograde Frequencies
| Planet | Frequency | Duration |
|---|---|---|
| Mercury | 3–4 times per year | ~3 weeks |
| Venus | Once every ~18 months | ~6 weeks |
| Mars | Once every ~2 years | ~2–3 months |
| Jupiter | Once per year | ~4 months |
| Saturn | Once per year | ~4.5 months |
| Uranus | Once per year | ~5 months |
| Neptune | Once per year | ~5 months |
| Pluto | Once per year | ~5–6 months |
| Chiron | Once per year | ~5 months |