Predictive Astrology
Transit calculations, sign ingresses, and timing forecasts.
Overview
Predictive astrology endpoints help you forecast future astrological events, calculate exact timing for transits, and search for significant planetary aspects over time.
POST /predictive/transits/planet-to-degree
Calculate when a planet crosses a specific degree of the zodiac.
Request Body
{
planet_name: "saturn" | "jupiter" | "mars" | "sun" | "moon" | "mercury" | "venus" | "uranus" | "neptune" | "pluto";
target_degree: number; // 0-360
start_date: string; // ISO 8601
max_crossings?: number; // Default: 10
}
Response
{
success: true;
transits: Array<{
exact_datetime: string;
planet: string;
degree: number;
retrograde: boolean;
crossing_number: number;
}>;
total_count: number;
}
Example
curl -X POST https://api.astromcp.io/predictive/transits/planet-to-degree \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"planet_name": "saturn",
"target_degree": 0,
"start_date": "2024-01-01T00:00:00",
"max_crossings": 5
}'
POST /predictive/transits/sign-ingresses
Calculate when planets enter new zodiac signs.
Request Body
{
planets: string[]; // e.g., ["sun", "moon", "mercury"]
start_date: string;
end_date: string;
}
Response
{
success: true;
ingresses: Array<{
planet: string;
sign: string; // "Aries", "Taurus", etc.
exact_datetime: string;
}>;
total_count: number;
}
Use Cases
- New Moon planning: Find when Moon enters specific signs
- Solar seasons: Track Sun's sign changes
- Outer planet ingresses: Major astrological shifts
- Electional astrology: Choose timing based on sign entries
POST /predictive/transits/search
Search for transit aspects between natal and transiting planets.
Request Body
{
natal_planets: Record<string, number>; // Planet name → degree
transiting_planets: string[]; // Which planets to check
start_date: string;
end_date: string;
aspects?: string[]; // ["conjunction", "square", "trine", "opposition"]
orb?: number; // Degrees (default: 1)
}
Response
{
success: true;
aspects: Array<{
exact_datetime: string;
natal_planet: string;
transiting_planet: string;
aspect: string;
orb: number;
applying: boolean;
}>;
total_count: number;
}
Example
curl -X POST https://api.astromcp.io/predictive/transits/search \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"natal_planets": {
"sun": 84.5,
"moon": 120.3
},
"transiting_planets": ["saturn", "jupiter"],
"start_date": "2024-01-01",
"end_date": "2024-12-31",
"aspects": ["conjunction", "square", "opposition"]
}'
POST /predictive/returns
Calculate the exact moment a body returns to its natal position, searched near a target datetime.
Request Body
{
body: "Sun" | "Moon" | string;
birth_datetime: { iso?: string };
target_datetime: { iso?: string };
location: {
latitude: { decimal: number };
longitude: { decimal: number };
timezone: { name?: string; iana_name?: string };
elevation?: number;
};
return_location?: {
latitude: { decimal: number };
longitude: { decimal: number };
timezone: { name?: string; iana_name?: string };
elevation?: number;
};
search_window_days?: number;
include_chart: boolean;
house_system?: string | null;
}
Example
curl -X POST https://api.astromcp.io/predictive/returns \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "Sun",
"birth_datetime": { "iso": "1990-06-15T14:30:00Z" },
"target_datetime": { "iso": "2024-06-15T00:00:00Z" },
"location": {
"latitude": { "decimal": 40.7128 },
"longitude": { "decimal": -74.0060 },
"timezone": { "name": "UTC" }
},
"include_chart": true,
"house_system": "P",
"search_window_days": 5
}'
Related Endpoints
- Transit Charts - Full transit chart calculation
- Return Charts - Solar & lunar return charts
- Progressed Charts - Secondary progressions