Declinações
Um mapa astral é uma projeção sobre a eclíptica, e essa projeção descarta um eixo. A declinação é o que resta quando os mesmos corpos são medidos a partir do equador celeste — a segunda tabela de uma efeméride impressa, e a coordenada que não aparece em nenhuma grelha de aspetos.
Nesse eixo vivem duas coisas, e nenhuma delas é visível num mapa zodiacal:
- Paralelos e contraparalelos. Dois corpos na mesma declinação formam um paralelo, que se comporta como uma conjunção. A mesma distância ao equador em lados opostos é um contraparalelo, que se comporta como uma oposição. Ambos podem ocorrer entre corpos que não formam qualquer aspeto em longitude.
- Fora dos limites (out of bounds). Um corpo além da declinação máxima do próprio Sol. A Lua está assim alguns dias por mês em torno de uma paragem lunar maior; Mercúrio, Vénus, Marte e Plutão a intervalos. É uma condição real e muito discutida, e quase nenhum software de consumo a reporta.
Módulo Necessário
Ambos os endpoints requerem o módulo declination:calc. Está incluído em todos os planos e não é vendido separadamente.
Declinações para um 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
}'Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
dateTime | string | Sim | YYYY-MM-DDTHH:mm, hora local do relógio em location |
location | object | Sim | latitude, longitude e um timezone IANA |
points | array | Não | Pontos a calcular. Por omissão os dez corpos, ambos os nodos e ambas as Lilith |
orb | number | Não | Orbe para paralelos e contraparalelos, de 0 a 3 graus. Por omissão 1 |
moonCenter | string | Não | topocentric (por omissão) ou geocentric |
Um orbe aqui não é um orbe ali
Um orbe de declinação é muito mais apertado do que um orbe de longitude. Um grau é a convenção e o valor por omissão; para além de dois graus, quase tudo está paralelo a algo.
Resposta
{
"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 é a magnitude como [graus, minutos, segundos]; o lado está em hemisphere e no sinal de declination. speedDeclination é em graus por dia, e negativo significa para sul — é o que indica se um paralelo está a aplicar-se ou a separar-se, a mesma pergunta a que applying responde para um aspeto em longitude.
O limite do fora dos limites
obliquity é a obliquidade verdadeira da eclíptica na data pedida — a declinação máxima do próprio Sol e, portanto, o limite face ao qual outOfBounds foi avaliado. É devolvida para que um cliente possa desenhar a faixa sem inventar o seu próprio limite.
O valor convencional é 23°26'. O real move-se: a nutação desloca-o até nove segundos de arco, e isso basta para decidir um caso limite num sentido ou noutro. Comparar com a obliquity devolvida e comparar com um 23.4367 fixo dá respostas diferentes para um corpo exatamente sobre a linha.
O Sol nunca está fora dos limites
Por definição — a condição é «além do Sol». Um corpo exatamente no limite não está fora dos limites; tem de estar para além dele.
Declinação ao longo de um período
A outra metade, e a razão pela qual isto é um endpoint próprio em vez de um campo de um mapa natal: um gráfico de declinação é uma série no tempo, e as datas em que um corpo atravessa o limite do fora dos limites são o que um astrólogo realmente anota.
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"]
}'Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
startDate | string | Sim | YYYY-MM-DD ou ISO 8601 |
endDate | string | Sim | YYYY-MM-DD ou ISO 8601 |
stepDays | number | Não | Dias entre pontos da série, de 0,25 a 30. Por omissão 1 |
points | array | Não | Pontos a traçar. Valores por omissão como acima |
Resposta
{
"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
}
]
}
}As passagens não são amostradas a stepDays
Uma saída da Lua para além do limite dura um par de dias. Uma série traçada com passo semanal passaria por cima dela — por isso as passagens são procuradas numa grelha mais fina do que aquela em que a série é devolvida, e cada uma é depois refinada contra a efeméride até ao segundo.
A consequência prática: um stepDays largo custa-lhe a forma da curva, nunca uma data de passagem. Peça a resolução de que o gráfico precisa e nada mais.
O limite da série
Uma série está limitada a 400 pontos. Um ano com passo diário são 365; uma década com passo diário são 3653 e volta como um 400 com o conselho de alargar o passo:
{
"error": "That range at a 1-day step is 3654 points; the limit is 400. Widen stepDays or shorten the range."
}De qualquer forma, isto é um único pedido. Construir a mesma tabela a partir de 400 chamadas individuais custa 400 pedidos da sua quota mensal; o endpoint de série calcula-os numa única passagem e conta como um.
Declinação num mapa natal
A partir da versão da API 2026-09-10, cada ponto de uma resposta de mapa natal também traz declination e outOfBounds, de modo que uma roda possa marcar um corpo fora dos limites sem uma segunda chamada:
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" } }'Um cliente numa versão anterior mantém a forma de resposta que sempre recebeu. Consulte Versionamento da API para saber como fixar uma versão.
A resposta natal traz apenas esses dois campos. Paralelos, contraparalelos, ascensão reta, velocidade de declinação e a série estão todos nos endpoints acima.
O que isto não é
Não há aqui vista 3D, e é deliberado. A imagem correta da declinação é uma linha contra um eixo; uma esfera celeste torna-a mais bonita sem a tornar mais clara.