Declinazioni
Un tema natale è una proiezione sull'eclittica, e quella proiezione scarta un asse. La declinazione è ciò che resta quando gli stessi corpi vengono misurati dall'equatore celeste — la seconda tabella di un'effemeride stampata, e la coordinata che non compare in nessuna griglia degli aspetti.
Su quell'asse vivono due cose, e nessuna delle due è visibile in una carta zodiacale:
- Paralleli e contro-paralleli. Due corpi alla stessa declinazione formano un parallelo, che si comporta come una congiunzione. La stessa distanza dall'equatore su lati opposti è un contro-parallelo, che si comporta come un'opposizione. Entrambi possono verificarsi fra corpi che in longitudine non formano alcun aspetto.
- Fuori limite (out of bounds). Un corpo oltre la declinazione massima del Sole stesso. La Luna lo è per qualche giorno al mese attorno a un lunistizio maggiore; Mercurio, Venere, Marte e Plutone a intervalli. È una condizione reale e molto discussa, e quasi nessun software di consumo la segnala.
Modulo Richiesto
Entrambi gli endpoint richiedono il modulo declination:calc. È incluso in ogni piano e non è venduto separatamente.
Declinazioni per un momento
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
}'Parametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
dateTime | string | Sì | YYYY-MM-DDTHH:mm, ora locale dell'orologio in location |
location | object | Sì | latitude, longitude e un timezone IANA |
points | array | No | Punti da calcolare. Per impostazione predefinita i dieci corpi, entrambi i nodi ed entrambe le Lilith |
orb | number | No | Orbe per paralleli e contro-paralleli, da 0 a 3 gradi. Predefinito 1 |
moonCenter | string | No | topocentric (predefinito) o geocentric |
Un orbe qui non è un orbe là
Un orbe di declinazione è molto più stretto di un orbe di longitudine. Un grado è la convenzione e il valore predefinito; oltre i due gradi quasi tutto è parallelo a qualcosa.
Risposta
{
"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 è il valore assoluto come [gradi, minuti, secondi]; il lato è in hemisphere e nel segno di declination. speedDeclination è in gradi al giorno, e negativo significa verso sud — è ciò che indica se un parallelo è applicativo o separativo, la stessa domanda a cui applying risponde per un aspetto in longitudine.
Il confine del fuori limite
obliquity è l'obliquità vera dell'eclittica alla data richiesta — la declinazione massima del Sole stesso e quindi il confine rispetto al quale è stato valutato outOfBounds. Viene restituita perché un client possa disegnare la fascia senza inventarsi un proprio limite.
Il valore convenzionale è 23°26'. Quello reale si muove: la nutazione lo sposta fino a nove secondi d'arco, e tanto basta a decidere un caso limite in un senso o nell'altro. Confrontare con l'obliquity restituita e confrontare con un 23.4367 fisso dà risposte diverse per un corpo esattamente sulla linea.
Il Sole non è mai fuori limite
Per definizione — la condizione è «oltre il Sole». Un corpo esattamente sul confine non è fuori limite; deve trovarsi oltre.
Declinazione lungo un periodo
L'altra metà, e la ragione per cui questo è un endpoint a sé e non un campo di un tema natale: un grafico di declinazione è una serie nel tempo, e le date in cui un corpo attraversa il confine del fuori limite sono ciò che un astrologo annota davvero.
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"]
}'Parametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
startDate | string | Sì | YYYY-MM-DD o ISO 8601 |
endDate | string | Sì | YYYY-MM-DD o ISO 8601 |
stepDays | number | No | Giorni fra i punti della serie, da 0,25 a 30. Predefinito 1 |
points | array | No | Punti da tracciare. Valori predefiniti come sopra |
Risposta
{
"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
}
]
}
}Gli attraversamenti non sono campionati a stepDays
Un'escursione della Luna oltre il confine dura un paio di giorni. Una serie tracciata a passo settimanale la scavalcherebbe — per questo gli attraversamenti vengono cercati su una griglia più fine di quella a cui la serie viene restituita, e ciascuno viene poi affinato sull'effemeride fino al secondo.
La conseguenza pratica: uno stepDays ampio vi costa la forma della curva, mai una data di attraversamento. Chiedete la risoluzione che serve al grafico e nulla di più.
Il limite della serie
Una serie è limitata a 400 punti. Un anno a passo giornaliero ne fa 365; un decennio a passo giornaliero ne fa 3653 e torna come 400 con il consiglio di allargare il passo:
{
"error": "That range at a 1-day step is 3654 points; the limit is 400. Widen stepDays or shorten the range."
}In entrambi i casi si tratta di una sola richiesta. Costruire la stessa tabella con 400 chiamate singole costa 400 richieste della vostra quota mensile; l'endpoint della serie le calcola in un'unica passata e conta come una.
Declinazione in un tema natale
Dalla versione API 2026-09-10 in poi, ogni punto di una risposta di tema natale porta anche declination e outOfBounds, così che una ruota possa marcare un corpo fuori limite senza una seconda chiamata:
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" } }'Un chiamante su una versione precedente mantiene la forma di risposta che ha sempre ricevuto. Vedi Versionamento dell'API per come fissare una versione.
La risposta natale porta solo quei due campi. Paralleli, contro-paralleli, ascensione retta, velocità di declinazione e la serie stanno tutti sugli endpoint qui sopra.
Cosa non è
Qui non c'è una vista 3D, ed è voluto. L'immagine corretta della declinazione è una linea contro un asse; una sfera celeste la rende più bella senza renderla più chiara.