Declinations
A horoscope is a projection onto the ecliptic, and that projection throws one axis away. Declination is what is left when the same bodies are measured from the celestial equator instead — the second table in a printed ephemeris, and the coordinate no aspect grid contains.
Two things live on that axis, and neither is visible in a zodiac chart:
- Parallels and contraparallels. Two bodies at the same declination form a parallel, which behaves like a conjunction. The same distance from the equator on opposite sides is a contraparallel, which behaves like an opposition. Both can occur between bodies with no zodiacal aspect between them at all.
- Out of bounds. A body past the Sun's own maximum declination. The Moon is out of bounds for a few days a month around a major lunar standstill; Mercury, Venus, Mars and Pluto go there at intervals. It is a real, widely discussed condition, and almost no consumer software reports it.
Required Module
Both endpoints require the declination:calc module. It is included in every plan and is not sold separately.
Declinations for a moment
curl -X POST "https://api.astroapi.cloud/api/calc/declination" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": {
"latitude": 52.37,
"longitude": 4.89,
"timezone": "Europe/Amsterdam"
},
"orb": 1
}'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dateTime | string | Yes | YYYY-MM-DDTHH:mm, local clock time at location |
location | object | Yes | latitude, longitude and an IANA timezone |
points | array | No | Celestial points to calculate. Defaults to the ten bodies, both nodes and both Liliths |
orb | number | No | Orb for parallels and contraparallels, 0–3 degrees. Default 1 |
moonCenter | string | No | topocentric (default) or geocentric |
Orbs here are not orbs there
A declination orb is far tighter than a longitude orb. One degree is the convention, and that is the default; past two degrees almost everything is parallel to something.
Response
{
"data": {
"dateTime": "1990-06-15T12:30:00.000Z",
"points": {
"sun": {
"pointId": "sun",
"declination": 23.32,
"declinationDms": [23, 19, 12],
"rightAscension": 84.1,
"latitude": 0,
"speedDeclination": 0.04,
"outOfBounds": false,
"hemisphere": "north"
},
"moon": {
"pointId": "moon",
"declination": -18.44,
"declinationDms": [18, 26, 24],
"rightAscension": 312.7,
"latitude": -4.61,
"speedDeclination": -3.1,
"outOfBounds": false,
"hemisphere": "south"
}
},
"aspects": [
{
"pointA": "venus",
"pointB": "mars",
"aspect": "parallel",
"orb": 0.31,
"applying": true,
"declinationA": 21.08,
"declinationB": 21.39
}
],
"extremes": {
"northernmost": "sun",
"southernmost": "moon",
"outOfBoundsCount": 0
},
"obliquity": 23.4405
}
}declinationDms is the magnitude as [degrees, minutes, seconds]; the side is in hemisphere and in the sign of declination. speedDeclination is degrees per day, and negative means southward — it is what tells you whether a parallel is applying or separating, the same question applying answers for a longitude aspect.
The out-of-bounds boundary
obliquity is the true obliquity of the ecliptic on the requested date — the Sun's own maximum declination, and therefore the boundary outOfBounds was judged against. It is returned so a client can draw the band without inventing its own limit.
The conventional figure is 23°26'. The real one moves: nutation shifts it by up to nine arcseconds, which is enough to decide a marginal case either way. Comparing against the returned obliquity and comparing against a hardcoded 23.4367 will disagree about a body sitting on the line.
The Sun is never out of bounds
By definition — the condition is "past the Sun". A body exactly at the limit is not out of bounds; it has to be beyond it.
Declination over a period
The other half, and the reason this is its own endpoint rather than a field on a natal chart: a declination graph is a series over time, and the dates a body crosses the out-of-bounds limit are what an astrologer actually writes down.
curl -X POST "https://api.astroapi.cloud/api/calc/declination/series" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2025-01-01",
"endDate": "2025-12-31",
"stepDays": 2,
"points": ["sun", "moon", "mercury", "venus", "mars", "pluto"]
}'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | YYYY-MM-DD or ISO 8601 |
endDate | string | Yes | YYYY-MM-DD or ISO 8601 |
stepDays | number | No | Days between series points, 0.25–30. Default 1 |
points | array | No | Celestial points to plot. Defaults as above |
Response
{
"data": {
"startDate": "2025-01-01T00:00:00.000Z",
"endDate": "2025-12-31T23:59:00.000Z",
"stepDays": 2,
"points": ["sun", "moon", "mercury", "venus", "mars", "pluto"],
"series": {
"moon": [
["2025-01-01T00:00:00.000Z", -14.02],
["2025-01-03T00:00:00.000Z", 8.71]
]
},
"crossings": [
{
"pointId": "moon",
"date": "2025-03-06T07:41:12.000Z",
"direction": "out",
"declination": 23.4392
},
{
"pointId": "moon",
"date": "2025-03-10T02:18:55.000Z",
"direction": "in",
"declination": 23.4392
}
]
}
}The crossings are not sampled at stepDays
A Moon excursion past the limit lasts a couple of days. A series plotted at a weekly step would step straight over it — so the crossings are searched on a grid finer than the one the series is returned at, and each one is then refined against the ephemeris to the second.
The practical consequence: a wide stepDays costs you the shape of the curve, never a crossing date. Ask for the resolution the graph needs and no more.
The series cap
A series is limited to 400 points. A year at a daily step is 365; a decade at a daily step is 3653 and comes back as a 400 with the advice to widen the step:
{
"error": "That range at a 1-day step is 3654 points; the limit is 400. Widen stepDays or shorten the range."
}This is one request either way. Building the same table out of 400 individual calls costs 400 requests against your monthly allowance; the series endpoint computes them in a single pass and counts as one.
Declination on a natal chart
From API version 2026-09-10 onwards, every point on a natal chart response also carries declination and outOfBounds, so a wheel can mark an out-of-bounds body without a second call:
curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
-H "X-Api-Key: your-api-key" \
-H "X-Api-Version: 2026-09-10" \
-H "Content-Type: application/json" \
-d '{ "dateTime": "1990-06-15T14:30", "location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" } }'A caller on an older version keeps the response shape it has always had. See API Versioning for how to pin a version.
The natal response carries only those two fields. Parallels, contraparallels, right ascension, declination speed and the series all live on the endpoints above.
What this is not
There is no 3D view here, and that is deliberate. The right picture of declination is a line against an axis; a celestial sphere makes it prettier without making it clearer.