Declinaties
Een horoscoop is een projectie op de ecliptica, en die projectie gooit één as weg. Declinatie is wat er overblijft wanneer dezelfde lichamen vanaf de hemelequator worden gemeten — de tweede tabel in een gedrukte ephemeride, en de coördinaat die in geen enkel aspectraster voorkomt.
Op die as leven twee dingen, en geen van beide is zichtbaar in een dierenriemkaart:
- Parallellen en contraparallellen. Twee lichamen op dezelfde declinatie vormen een parallel, die werkt als een conjunctie. Dezelfde afstand tot de equator aan tegengestelde zijden is een contraparallel, die werkt als een oppositie. Beide kunnen optreden tussen lichamen die in lengtegraad niets met elkaar te maken hebben.
- Out of bounds. Een lichaam voorbij de maximale declinatie van de Zon zelf. De Maan is dat een paar dagen per maand rond een grote maanstilstand; Mercurius, Venus, Mars en Pluto met tussenpozen. Het is een reële, veelbesproken conditie, en vrijwel geen consumentensoftware meldt hem.
Vereiste module
Beide endpoints vereisen de declination:calc module. Die zit in elk plan en is niet apart te koop.
Declinaties voor één 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 | Verplicht | Beschrijving |
|---|---|---|---|
dateTime | string | Ja | YYYY-MM-DDTHH:mm, lokale kloktijd op location |
location | object | Ja | latitude, longitude en een IANA-timezone |
points | array | Nee | Te berekenen punten. Standaard de tien lichamen, beide knopen en beide Liliths |
orb | number | Nee | Orb voor parallellen en contraparallellen, 0–3 graden. Standaard 1 |
moonCenter | string | Nee | topocentric (standaard) of geocentric |
Een orb hier is niet een orb daar
Een declinatie-orb is veel krapper dan een lengtegraad-orb. Eén graad is de conventie en de standaardwaarde; voorbij twee graden staat vrijwel alles parallel aan iets.
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 de grootte als [graden, minuten, seconden]; de kant staat in hemisphere en in het teken van declination. speedDeclination is graden per dag, en negatief betekent zuidwaarts — dat is wat je vertelt of een parallel aanloopt of uitloopt, dezelfde vraag die applying beantwoordt voor een lengtegraad-aspect.
De out-of-bounds-grens
obliquity is de ware scheefheid van de ecliptica op de gevraagde datum — de maximale declinatie van de Zon zelf, en dus de grens waartegen outOfBounds is beoordeeld. Hij wordt meegegeven zodat een client de band kan tekenen zonder een eigen grens te verzinnen.
De conventionele waarde is 23°26'. De echte beweegt: nutatie verschuift hem tot negen boogseconden, en dat is genoeg om een grensgeval de ene of de andere kant op te laten vallen. Vergelijken met de teruggegeven obliquity en vergelijken met een vaste 23.4367 zijn het oneens over een lichaam dat precies op de lijn staat.
De Zon is nooit out of bounds
Per definitie — de conditie is "voorbij de Zon". Een lichaam precies op de grens staat er niet buiten; het moet er voorbij zijn.
Declinatie over een periode
De andere helft, en de reden dat dit een eigen endpoint is in plaats van een veld op een natale kaart: een declinatiegrafiek is een reeks over tijd, en de datums waarop een lichaam de out-of-bounds-grens kruist zijn wat een astroloog daadwerkelijk opschrijft.
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 | Verplicht | Beschrijving |
|---|---|---|---|
startDate | string | Ja | YYYY-MM-DD of ISO 8601 |
endDate | string | Ja | YYYY-MM-DD of ISO 8601 |
stepDays | number | Nee | Dagen tussen reekspunten, 0,25–30. Standaard 1 |
points | array | Nee | Te plotten punten. Standaardwaarden als hierboven |
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
}
]
}
}De kruisingen worden niet op stepDays bemonsterd
Een uitstapje van de Maan voorbij de grens duurt een paar dagen. Een reeks die per week wordt geplot zou er dwars overheen stappen — daarom worden de kruisingen gezocht op een raster dat fijner is dan waarop de reeks wordt teruggegeven, en wordt elke kruising daarna tegen de ephemeride verfijnd tot op de seconde.
Het praktische gevolg: een brede stepDays kost je de vorm van de curve, nooit een kruisingsdatum. Vraag de resolutie die de grafiek nodig heeft en niet meer.
De reeksgrens
Een reeks is begrensd op 400 punten. Een jaar met een dagstap is er 365; een decennium met een dagstap is er 3653 en komt terug als een 400 met het advies de stap te vergroten:
{
"error": "That range at a 1-day step is 3654 points; the limit is 400. Widen stepDays or shorten the range."
}Dit is hoe dan ook één request. Dezelfde tabel opbouwen uit 400 losse aanroepen kost 400 requests van je maandelijkse tegoed; het reeks-endpoint berekent ze in één pass en telt als één.
Declinatie op een natale kaart
Vanaf API-versie 2026-09-10 draagt elk punt op een natale kaart ook declination en outOfBounds, zodat een wiel een out-of-bounds-lichaam kan markeren zonder een tweede aanroep:
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" } }'Een beller op een oudere versie houdt de responsevorm die hij altijd al kreeg. Zie API-versionering voor hoe je een versie vastzet.
De natale response draagt alleen die twee velden. Parallellen, contraparallellen, rechte klimming, declinatiesnelheid en de reeks staan allemaal op de endpoints hierboven.
Wat dit niet is
Er is hier geen 3D-weergave, en dat is met opzet. Het juiste beeld van declinatie is een lijn tegen een as; een hemelbol maakt het mooier zonder het duidelijker te maken.