🔮 Horoscopes
POST
/api/horoscope/daily/{date?}
Daily Horoscope
Get daily horoscope with optional natal chart comparison.
🌍 General Daily Horoscope (No Birth Data)
Get universal planetary positions and events for a specific date. Same for everyone
worldwide - no location required.
Request Body (General)
POST /api/horoscope/daily/2024-01-15 Content-Type: application/json { "location": {
"latitude": 40.7128, "longitude": -74.0060 }, "time": "12:00:00" }
Response (General)
{ "success": true, "data": { "date": "2024-01-15", "julianDay": 2460324.0, "planets": {
"sun": { "longitude": 294.56, "latitude": 0.0, "speed": 1.02, "isRetrograde": false,
"house": 10 }, "moon": { "longitude": 45.67, "latitude": 2.34, "speed": 13.45,
"isRetrograde": false, "house": 2 } }, "houses": { "houses": { "house1": 245.67,
"house2": 275.89 }, "ascendant": 245.67, "midheaven": 175.23 }, "moonPhase":
"WAXING_CRESCENT", "ingresses": [ { "planet": "mercury", "fromSign": "Capricorn",
"toSign": "Aquarius", "date": "2024-01-15" } ], "retrogradeEvents": [] } }
👤 Personalized Daily Horoscope (With Birth Data)
Get personalized horoscope with natal-transit aspects (how current planets aspect your
birth chart). The birth chart is calculated once and reused efficiently.
Request Body (Personalized)
POST /api/horoscope/daily/2024-01-15 Content-Type: application/json { "birthData": {
"name": "John Doe", "birthDate": "1990-05-15", "birthTime": "14:30:00", "latitude":
40.7128, "longitude": -74.0060, "location": "New York, NY" }, "location": { "latitude":
40.7128, "longitude": -74.0060 }, "time": "12:00:00" }
Response (Personalized)
{ "success": true, "data": { "date": "2024-01-15", "julianDay": 2460324.0, "planets": {
"sun": { "longitude": 294.56, "latitude": 0.0, "speed": 1.02, "isRetrograde": false,
"house": 10 }, "moon": { "longitude": 45.67, "latitude": 2.34, "speed": 13.45,
"isRetrograde": false, "house": 2 } }, "houses": { "houses": { "house1": 245.67,
"house2": 275.89 }, "ascendant": 245.67, "midheaven": 175.23 }, "moonPhase":
"WAXING_CRESCENT", "ingresses": [ { "planet": "mercury", "fromSign": "Capricorn",
"toSign": "Aquarius", "date": "2024-01-15" } ], "retrogradeEvents": [],
"natalTransitAspects": [ { "point1": "sun", "point2": "moon", "aspectType": "trine",
"orb": 1.5, "orbFormatted": "1°30'", "applying": true, "description": "Sun trine Moon",
"aspectCategory": "planet_aspect", "score": 8 } ] } }
POST
/api/horoscope/weekly/{date?}
Weekly Horoscope
Get weekly horoscope with key events and planetary movements for the week containing the
specified date.
🌍 General Weekly Horoscope (No Birth Data)
Get universal planetary events and overview for the week containing the specified date
(Monday to Sunday). Same for everyone worldwide - no location required.
Request Body (General)
POST /api/horoscope/weekly/2025-01-15 Content-Type: application/json { "location": {
"latitude": 40.7128, "longitude": -74.0060 } }
Response (General)
{ "success": true, "data": { "year": 2025, "week": 3, "weekStart": "2025-01-13",
"weekEnd": "2025-01-19", "weekDescription": "Week 3, 2025", "weekEvents": [ { "date":
"2025-01-15", "dayName": "Wednesday", "type": "ingress", "events": [ { "planet":
"mercury", "fromSign": "Capricorn", "toSign": "Aquarius", "date": "2025-01-15",
"description": "Mercury enters Aquarius" } ] } ], "weekOverview": { "midWeekDate":
"2025-01-16", "planets": { "sun": { "degrees": 295.23, "zodiac": "Capricorn 25°14'" },
"moon": { "degrees": 45.67, "zodiac": "Taurus 15°40'" } }, "moonPhase": "WANING_GIBBOUS"
}, "isPersonalized": false } }
👤 Personalized Weekly Horoscope (With Birth Data)
Get personalized weekly horoscope with significant natal-transit aspects and events
specifically affecting your birth chart.
Request Body (Personalized)
POST /api/horoscope/weekly/2025-01-15 Content-Type: application/json { "birthData": {
"name": "John Doe", "birthDate": "1990-05-15", "birthTime": "14:30:00", "latitude":
40.7128, "longitude": -74.0060, "location": "New York, NY" } }
Response (Personalized)
{ "success": true, "data": { "year": 2025, "week": 3, "weekStart": "2025-01-13",
"weekEnd": "2025-01-19", "weekDescription": "Week 3, 2025", "weekEvents": [ { "date":
"2025-01-15", "dayName": "Wednesday", "type": "aspects", "events": [ { "point1": "sun",
"point2": "venus", "aspectType": "natal_transit", "orb": 1.2, "orbFormatted": "1°12'",
"applying": true, "description": "Transiting Sun conjunct natal Venus", "score": 8 } ] }
], "weekOverview": { "midWeekDate": "2025-01-16", "planets": { "sun": { "degrees":
295.23, "zodiac": "Capricorn 25°14'" }, "moon": { "degrees": 45.67, "zodiac": "Taurus
15°40'" } }, "moonPhase": "WANING_GIBBOUS", "houses": { "ascendant": { "degrees":
346.78, "zodiac": "Pisces 16°47'" }, "midheaven": { "degrees": 262.28, "zodiac":
"Sagittarius 22°17'" } } }, "isPersonalized": true } }
POST
/api/horoscope/monthly/{date?}
Monthly Horoscope
Get monthly horoscope with key events and planetary movements for the month containing the
specified date.
🌍 General Monthly Horoscope (No Birth Data)
Request Body (General)
POST /api/horoscope/monthly/2024/01 Content-Type: application/json { "location": {
"latitude": 40.7128, "longitude": -74.0060 } }
👤 Personalized Monthly Horoscope (With Birth Data)
Request Body (Personalized)
POST /api/horoscope/monthly/2024/01 Content-Type: application/json { "birthData": {
"name": "John Doe", "birthDate": "1990-05-15", "birthTime": "14:30:00", "latitude":
40.7128, "longitude": -74.0060, "location": "New York, NY" }, "location": { "latitude":
40.7128, "longitude": -74.0060 } }
POST
/api/horoscope/annual/{year?}
Annual Horoscope
Get annual horoscope with major transits and predictions.
🌍 General Annual Horoscope (No Birth Data)
Get universal annual horoscope with major transits and predictions. Same for everyone
worldwide - no location required.
Request Body (General)
POST /api/horoscope/annual/2024 Content-Type: application/json { "location": {
"latitude": 40.7128, "longitude": -74.0060 } }
👤 Personalized Annual Horoscope (With Birth Data)
Request Body (Personalized)
POST /api/horoscope/annual/2024 Content-Type: application/json { "birthData": { "name":
"John Doe", "birthDate": "1990-05-15", "birthTime": "14:30:00", "latitude": 40.7128,
"longitude": -74.0060, "location": "New York, NY" }, "location": { "latitude": 40.7128,
"longitude": -74.0060 } }
POST
/api/horoscope/retrograde-stations
Find Retrograde Stations
Find dates when planets go retrograde or direct.
Request Body
| Field |
Type |
Required |
Description |
| planetName |
string |
Yes |
Planet name (e.g., "mars", "venus") |
| startDate |
string |
Yes |
Start date in YYYY-MM-DD format |
| endDate |
string |
Yes |
End date in YYYY-MM-DD format |
Example Request
POST /api/horoscope/retrograde-stations Content-Type: application/json { "planetName":
"mars", "startDate": "2024-01-01", "endDate": "2024-12-31" }
Example Response
{ "success": true, "data": [ { "planet": "mars", "date": "2024-12-06", "type":
"retrograde", "description": "Mars goes retrograde in Leo" }, { "planet": "mars", "date":
"2025-02-23", "type": "direct", "description": "Mars goes direct in Cancer" } ] }
POST
/api/horoscope/comprehensive
Comprehensive Data
Get all astrology data needed for backend integration in a single request.
Request Body
| Field |
Type |
Required |
Description |
| birthData |
object |
Yes |
Birth data for natal chart |
| location |
object |
No |
Location for calculations |
| date |
string |
No |
Target date (defaults to today) |
| year |
string |
No |
Target year |
| month |
string |
No |
Target month |
Example Request
POST /api/horoscope/comprehensive Content-Type: application/json { "birthData": { "name":
"John Doe", "birthDate": "1990-05-15", "birthTime": "14:30:00", "latitude": 40.7128,
"longitude": -74.0060, "location": "New York, NY" }, "date": "2024-01-15" }
Example Response
{ "success": true, "data": { "user": { "name": "John Doe", "birthDate": "1990-05-15",
"birthTime": "14:30:00", "latitude": 40.7128, "longitude": -74.0060, "location": "New
York, NY" }, "natalChart": { "birthDateTime": "1990-05-15T14:30:00", "birthLocation": {
"name": "New York, NY", "latitude": 40.7128, "longitude": -74.0060, "tzId": "UTC" },
"houseSystem": "PLACIDUS", "natalPlanets": [ { "planet": "SUN", "dateTime":
"1990-05-15T14:30:00", "longitude": 54.32, "latitude": 0.0, "speed": 1.02, "isRetrograde":
false, "house": 3 } ], "houses": [ { "number": 1, "cuspLongitude": 245.67 } ],
"natalAspects": [ { "a": "SUN", "b": "MOON", "type": "CONJUNCTION", "orb": 2.5,
"exactDelta": 2.5 } ], "angles": { "ascendant": 245.67, "descendant": 65.67, "midheaven":
175.23, "fortune": 123.45 } }, "transitSet": { "dateRange": { "start": "2024-01-15",
"end": "2024-01-15", "granularity": "DAILY" }, "positions": [ { "planet": "SUN",
"dateTime": "2024-01-15T00:00:00", "longitude": 294.56, "latitude": 0.0, "speed": 1.02,
"isRetrograde": false } ], "moonPhase": "NEW", "ingresses": [], "retrogrades": [] },
"horoscope": { "dateRange": { "start": "2024-01-15", "end": "2024-01-15", "granularity":
"DAILY" }, "granularity": "DAILY", "items": [ { "type": "AspectHit", "score": 10,
"summary": "Sun conjunct Moon", "detail": "A powerful conjunction aspect" } ], "text":
"Daily horoscope for 2024-01-15", "metadata": { "totalAspects": 5, "totalEvents": 2,
"moonPhase": "WAXING_CRESCENT" } }, "calculationMetadata": { "timestamp":
"2024-01-15T12:00:00.000Z", "ephemerisVersion": "Swiss Ephemeris", "calculationAccuracy":
"High precision" } } }
POST
/api/horoscope/transit-data
Transit Data
Get transit data for a specific date range with natal chart comparison.
Request Body
| Field |
Type |
Required |
Description |
| startDate |
string |
Yes |
Start date in YYYY-MM-DD format |
| endDate |
string |
Yes |
End date in YYYY-MM-DD format |
| birthData |
object |
Yes |
Birth data for natal chart |
| location |
object |
No |
Location for calculations |
Example Request
POST /api/horoscope/transit-data Content-Type: application/json { "startDate":
"2024-01-01", "endDate": "2024-01-31", "birthData": { "name": "John Doe", "birthDate":
"1990-05-15", "birthTime": "14:30:00", "latitude": 40.7128, "longitude": -74.0060,
"location": "New York, NY" }, "location": { "latitude": 40.7128, "longitude": -74.0060 } }
🔮 Dedicated Astrology Endpoints
Specialized endpoints for advanced astrological data and integrations.
GET
/api/astrology/ingresses
Planetary Ingresses
Get planetary ingresses (sign changes) for a specific date range.
Query Parameters
| Parameter |
Type |
Required |
Description |
startDate |
string |
Yes |
Start date (YYYY-MM-DD) |
endDate |
string |
Yes |
End date (YYYY-MM-DD) |
planets |
string |
No |
Comma-separated planet names (e.g., "mercury,venus,mars") |
Example Request
GET
/api/astrology/ingresses?startDate=2024-01-01&endDate=2024-12-31&planets=mercury,venus,mars
Example Response
{ "success": true, "data": { "startDate": "2024-01-01", "endDate": "2024-12-31",
"totalIngresses": 3, "ingresses": [ { "planet": "mercury", "fromSign": "Capricorn",
"toSign": "Aquarius", "date": "2024-01-15", "longitude": 300.0, "description": "mercury
enters Aquarius" }, { "planet": "venus", "fromSign": "Sagittarius", "toSign": "Capricorn",
"date": "2024-01-23", "longitude": 270.0, "description": "venus enters Capricorn" }, {
"planet": "mars", "fromSign": "Libra", "toSign": "Scorpio", "date": "2024-02-08",
"longitude": 210.0, "description": "mars enters Scorpio" } ] } }
GET
/api/astrology/retrograde-stations
Retrograde Stations
Get retrograde stations for a specific date range.
Query Parameters
| Parameter |
Type |
Required |
Description |
startDate |
string |
Yes |
Start date (YYYY-MM-DD) |
endDate |
string |
Yes |
End date (YYYY-MM-DD) |
planets |
string |
No |
Comma-separated planet names (e.g., "mercury,venus") |
Example Request
GET
/api/astrology/retrograde-stations?startDate=2024-01-01&endDate=2024-12-31&planets=mercury,venus
Example Response
{ "success": true, "data": { "startDate": "2024-01-01", "endDate": "2024-12-31",
"totalStations": 4, "stations": [ { "planet": "mercury", "date": "2024-01-01", "type":
"retrograde", "description": "Mercury goes retrograde in Capricorn" }, { "planet":
"mercury", "date": "2024-01-21", "type": "direct", "description": "Mercury goes direct in
Capricorn" }, { "planet": "venus", "date": "2024-07-22", "type": "retrograde",
"description": "Venus goes retrograde in Leo" }, { "planet": "venus", "date":
"2024-09-03", "type": "direct", "description": "Venus goes direct in Leo" } ] } }
GET
/api/astrology/moon-phases
Moon Phases
Get moon phases for a specific date range.
Query Parameters
| Parameter |
Type |
Required |
Description |
startDate |
string |
Yes |
Start date (YYYY-MM-DD) |
endDate |
string |
Yes |
End date (YYYY-MM-DD) |
phases |
string |
No |
Comma-separated phases (e.g., "NEW_MOON,FULL_MOON") |
Example Request
GET
/api/astrology/moon-phases?startDate=2024-01-01&endDate=2024-01-31&phases=NEW_MOON,FULL_MOON
Example Response
{ "success": true, "data": { "startDate": "2024-01-01", "endDate": "2024-01-31",
"totalPhases": 2, "moonPhases": [ { "date": "2024-01-11", "phase": "NEW_MOON",
"sunLongitude": 290.5, "moonLongitude": 290.5, "phaseAngle": 0.0 }, { "date":
"2024-01-25", "phase": "FULL_MOON", "sunLongitude": 305.2, "moonLongitude": 125.2,
"phaseAngle": 180.0 } ] } }