Skip to content

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 ​

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
  }'

Parâmetros ​

ParâmetroTipoObrigatórioDescrição
dateTimestringSimYYYY-MM-DDTHH:mm, hora local do relógio em location
locationobjectSimlatitude, longitude e um timezone IANA
pointsarrayNãoPontos a calcular. Por omissão os dez corpos, ambos os nodos e ambas as Lilith
orbnumberNãoOrbe para paralelos e contraparalelos, de 0 a 3 graus. Por omissão 1
moonCenterstringNãotopocentric (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 ​

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

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"]
  }'

Parâmetros ​

ParâmetroTipoObrigatórioDescrição
startDatestringSimYYYY-MM-DD ou ISO 8601
endDatestringSimYYYY-MM-DD ou ISO 8601
stepDaysnumberNãoDias entre pontos da série, de 0,25 a 30. Por omissão 1
pointsarrayNãoPontos a traçar. Valores por omissão como acima

Resposta ​

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
      }
    ]
  }
}

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:

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

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" } }'

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.

AstroAPI Documentation