Skip to content

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 ​

bash
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 ​

ParametroTipoObbligatorioDescrizione
dateTimestringSìYYYY-MM-DDTHH:mm, ora locale dell'orologio in location
locationobjectSìlatitude, longitude e un timezone IANA
pointsarrayNoPunti da calcolare. Per impostazione predefinita i dieci corpi, entrambi i nodi ed entrambe le Lilith
orbnumberNoOrbe per paralleli e contro-paralleli, da 0 a 3 gradi. Predefinito 1
moonCenterstringNotopocentric (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 ​

json
{
  "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.

bash
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 ​

ParametroTipoObbligatorioDescrizione
startDatestringSìYYYY-MM-DD o ISO 8601
endDatestringSìYYYY-MM-DD o ISO 8601
stepDaysnumberNoGiorni fra i punti della serie, da 0,25 a 30. Predefinito 1
pointsarrayNoPunti da tracciare. Valori predefiniti come sopra

Risposta ​

json
{
  "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:

json
{
  "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:

bash
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.

AstroAPI Documentation