POST/api/astro/celestial/1 crédito

Posições celestes

Efemérides brutas de um ou mais corpos: onde um planeta está, a que velocidade se move, quando nasce e se põe, se está retrógrado. É a camada astronômica que sustenta o resto da API, exposta diretamente, e vai muito além dos nove grahas védicos — os planetas exteriores, Quíron e os asteroides, os pontos fictícios uranianos e várias luas planetárias estão todos disponíveis. As chaves são de dois tipos. As chaves `set_*` são seletores: mudam a forma de calcular as posições ou os horários de nascer e pôr — geocêntrico, topocêntrico ou heliocêntrico, aparente ou verdadeiro, com ou sem nutação, sideral ou tropical, nascer hindu ou nascer pelo centro do disco — e cada uma retorna null. As chaves `get_*`, junto com `rise_time`, `set_time`, `is_retrograde` e `is_stationary`, retornam valores. Como as chaves são executadas na ordem em que você as lista, um seletor só afeta as chaves de valor que vêm depois dele no array. `planet_names` recebe uma lista de nomes em maiúsculas, e a resposta é indexada por eles; assim, uma chamada para MARS volta como `{"data": {"MARS": {"get_longitude": 123.45}}}`. Um nome não reconhecido não faz a requisição falhar: essa entrada volta como `{"error": "Unknown planet '<name>'"}`. Observe que aqui os nodos se chamam MEAN_NODE e TRUE_NODE, e não seguem a grafia 'northtruenode' de /api/astro/chart/.

https://api.occultapi.com/api/astro/celestial/

Testar requisição

Autenticação

Envie sua chave no cabeçalho X-API-Key. A chave é uma credencial de servidor — nunca a coloque no JavaScript do navegador nem num app mobile.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Campos da requisição

Campo	Tipo	Obrigatório	Observações
altitude	number (double)	obrigatório
date_time	string (date-time)	obrigatório	O momento a calcular, em ISO 8601. SEMPRE inclua um deslocamento ou um Z no final - um valor sem fuso horário é lido como Asia/Kolkata (UTC+05:30), não como UTC, e pode retornar o resultado do dia anterior com um 200. '2026-09-01T06:00:00Z' e '2026-09-01 06:00:00' são instantes diferentes e dão respostas diferentes. Restrição de FORMATO, não um enum. DRF DateTimeField: apenas ISO-8601 (formatos de entrada padrão do DRF), por exemplo "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" ou "2026-09-01 06:00:00" (sem fuso horário = assume-se UTC).
keys	array	obrigatório	Quais cálculos retornar, como uma lista de nomes. Veja a tabela de chaves deste endpoint; um nome não reconhecido rejeita a requisição inteira. Uma chamada custa um crédito, não importa quantas chaves você peça, então solicite tudo o que precisa de uma vez em vez de fazer várias chamadas. `set_default_risingset_hindu_risingset_disc_center_refractionset_disc_bottom_refractionset_disc_center_no_refractionset_disc_bottom_no_refractionset_default_positionsset_true_positionsset_topocentric_positionsset_heliocentric_positionsset_barycentric_positionsset_astrometric_positions` Array de strings. As chaves `set_` alteram flags de cálculo no objeto Celestial; as chaves `get_` / `rise_time` / `set_time` / `is_*` retornam valores.
planet_names	array	obrigatório	`SUNMOONMERCURYVENUSMARSJUPITERSATURNURANUSNEPTUNEPLUTOMEAN_NODETRUE_NODE` Array de strings, com comprimento mínimo 1. Observe que os nodos se chamam 'MEAN_NODE'/'TRUE_NODE' aqui, e não seguem o estilo 'northtruenode' usado na saída do mapa. Um nome não reconhecido não faz a requisição falhar: essa entrada é retornada como {"error": "Unknown planet '<X>'"}.
time_zone	number (double)	obrigatório	min -12 · max 14
latitude	number (double)	opcional	Latitude do local, em graus decimais. Positivo é norte, negativo é sul. Exemplo: 26.9124 para Jaipur, 40.7128 para Nova York. Minutos e segundos não são aceitos - converta antes. min -89.9 · max 89.9
longitude	number (double)	opcional	Longitude do local, em graus decimais. Positivo é leste, negativo é oeste. Exemplo: 75.7873 para Jaipur, -74.0060 para Nova York. Atenção ao sinal: sem o sinal de menos, Nova York vai parar na China. min -180 · max 180

Chaves disponíveis (31)

Liste em keys só os cálculos que você quer. Uma chave desconhecida faz a requisição inteira ser rejeitada. O custo é 1 crédito, não importa quantas chaves você peça — então agrupe tudo numa chamada só.

Chave	Campos extras exigidos	Descrição
get_altitude	date_time, latitude, longitude, altitude	Altura do corpo acima do horizonte, em graus com seis casas decimais; negativo significa abaixo do horizonte. Requer `latitude`, `longitude` e `altitude` em metros.
get_apsis	date_time	O próximo afélio e o próximo periélio, os pontos em que o corpo fica mais longe e mais perto do Sol. Retorna um objeto `{Aphelion, Perihelion}` com uma data e hora UTC para cada um, encontradas por uma busca para a frente a partir do momento informado. Disponível apenas para os corpos que o modelo cobre.
get_azimuth	date_time, latitude, longitude, altitude	Onde procurar o corpo ao longo do horizonte, em graus no sentido horário a partir do norte, como um único número com seis casas decimais. Requer `latitude`, `longitude` e `altitude`, e leva em conta a refração, a menos que um seletor sem refração tenha sido definido antes.
get_declination	date_time	Declinação, a distância angular do corpo ao norte ou ao sul do equador celeste, como um objeto com `degrees`, `minutes` e `seconds`.
get_distance	date_time	Distância até o observador em unidades astronômicas, arredondada para três casas decimais. Um único número; para a Lua, é uma pequena fração de uma AU.
get_ecliptic_speeds	date_time	Velocidade do corpo, como um objeto com `longitude_speed` e `latitude_speed` em graus por dia e `distance_speed` em AU por dia, cada um com seis casas decimais. Uma velocidade em longitude negativa significa retrógrado.
get_equatorial_speeds	date_time	Movimento em coordenadas equatoriais: um objeto com `right_ascension_speed` e `declination_speed` em graus por dia e `distance_speed` em AU por dia, cada um com seis casas decimais.
get_illumination	date_time	A magnitude visual aparente do corpo naquele momento, como um único número com seis casas decimais — quanto menor e mais negativa, mais brilhante. Disponível apenas para os corpos que o modelo de iluminação cobre; os demais geram um erro.
get_latitude	date_time	Latitude eclíptica em graus com três casas decimais: a que distância o corpo está acima ou abaixo do plano da eclíptica. Um único número, negativo para o sul.
get_longitude	date_time	Longitude eclíptica em graus, de 0 a 360, arredondada para três casas decimais — um único número. Se é tropical ou sideral depende do modo de posição em vigor.
get_right_ascension	date_time	Ascensão reta, a contraparte equatorial da longitude, como um objeto com `hours`, `minutes` e `seconds`, em vez de graus decimais.
is_retrograde	date_time	True quando a velocidade em longitude do corpo é negativa, ou seja, quando ele parece se mover para trás pelo zodíaco. Um único booleano.
is_stationary	date_time	Uma verificação aproximada de estado estacionário: true quando a parte fracionária da velocidade diária em longitude do corpo, arredondada para três casas decimais, dá zero. Retorna um booleano e, por causa desse teste, é um indicador, e não uma estação exata.
rise_time	date_time, geopos	O nascer do corpo, buscado a partir da meia-noite local (o deslocamento de `time_zone`) da data informada, no local indicado. Retorna uma lista de dois elementos: o momento do nascer como data e hora, na hora local implícita em `time_zone`, e depois os números brutos do dia juliano. A definição de 'nascer' usada depende do seletor de nascer ou de disco que vier antes desta chave no array. Se o corpo não nascer ou não se puser dentro da janela de busca - a Lua em latitude alta, ou o Sol durante um dia polar -, a busca subjacente falha e a chave retorna "2000-11-24T12:00:00Z", que é o dia juliano zero, e não um instante real. Trate esse valor exato como ausência de resultado. /api/astro/sunrise/ e /api/astro/moonrise/ retornam null no mesmo caso.
set_astrometric_j_positions	—	Muda para posições astrométricas referidas ao equinócio médio de J2000, com nutação, aberração e deflexão da luz desativadas. Retorna null.
set_astrometric_positions	—	Muda para posições astrométricas: o tempo-luz é corrigido, mas a aberração anual e a deflexão gravitacional da luz não são. Retorna null.
set_barycentric_positions	—	Muda para posições baricêntricas, referidas ao baricentro do sistema solar. Retorna null e só funciona para corpos físicos — não para os nodos nem para os apogeus.
set_default_positions	—	Um seletor, não um valor: define posições geocêntricas aparentes com velocidades, que é o padrão TROPICAL deste endpoint. Retorna null. Os seletores `set_*` só se aplicam às chaves listadas depois deles em `keys`, então a ordem importa - coloque este primeiro, ou depois de outro seletor para voltar ao padrão. Atenção: em /api/astro/star/, a chave de mesmo nome define posições SIDERAIS.
set_default_rising	—	Restaura a definição padrão de nascer e pôr para `rise_time` e `set_time`. Um seletor, não um valor — retorna null e só afeta as chaves listadas depois dele.
set_disc_bottom_no_refraction	—	Calcula os horários de nascer e pôr a partir da borda inferior do disco, com a refração desativada. Retorna null.
set_disc_bottom_refraction	—	Calcula os horários de nascer e pôr a partir da borda inferior do disco, com a refração atmosférica aplicada. Retorna null.
set_disc_center_no_refraction	—	Calcula os horários de nascer e pôr a partir do centro do disco, com a refração desativada — geométricos em vez de observados. Retorna null e faz com que quaisquer `get_azimuth` e `get_altitude` posteriores sejam calculados sem atmosfera.
set_disc_center_refraction	—	Calcula os horários de nascer e pôr a partir do centro do disco, com a refração atmosférica aplicada. Retorna null e também faz com que quaisquer `get_azimuth` e `get_altitude` posteriores usem posições refratadas.
set_heliocentric_positions	—	Muda para posições heliocêntricas, referidas ao centro do Sol. Retorna null. O Sol, os nodos lunares e os apogeus lunares são retornados como zero neste modo.
set_hindu_rising	—	Muda os horários de nascer e pôr para a convenção hindu. Retorna null; afeta as chaves `rise_time` e `set_time` listadas depois deste seletor no array.
set_jpl_horizons_positions	—	Muda para posições aparentes calculadas como no JPL Horizons, para conferência com esse serviço. Retorna null.
set_mean_equinox_positions	—	Muda para posições referidas ao equinócio médio da data, desativando a nutação. Retorna null.
set_sidereal_positions	—	Muda para posições siderais, ou seja, a longitude tropical menos o ayanamsa. Retorna null. O próprio ayanamsa é definido em outro lugar, então vale o modo sideral em vigor.
set_time	date_time, geopos	O pôr do corpo, buscado a partir da meia-noite local (o deslocamento de `time_zone`) da data informada, no local indicado. Mesmo formato de `rise_time`: [data e hora local, números brutos do dia juliano]. Apesar do prefixo `set_`, esta chave retorna um valor; ela não é um dos seletores. Se o corpo não nascer ou não se puser dentro da janela de busca - a Lua em latitude alta, ou o Sol durante um dia polar -, a busca subjacente falha e a chave retorna "2000-11-24T12:00:00Z", que é o dia juliano zero, e não um instante real. Trate esse valor exato como ausência de resultado. /api/astro/sunrise/ e /api/astro/moonrise/ retornam null no mesmo caso.
set_topocentric_positions	latitude, longitude, altitude	Muda para posições topocêntricas, referidas ao local do próprio observador em vez do centro da Terra. Requer `latitude`, `longitude` e `altitude` em metros; retorna null. A diferença só é perceptível para a Lua.
set_true_positions	—	Muda para posições geométricas verdadeiras, sem considerar o tempo-luz — onde o corpo realmente está, e não onde parece estar. Retorna null.

Exemplo de requisição

curl -X POST https://api.occultapi.com/api/astro/celestial/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2024-11-20T08:40:08.658Z","keys":["set_default_positions","set_hindu_rising"],"latitude":26.9124,"longitude":75.7873,"time_zone":5.5,"altitude":0,"planet_names":["SUN"]}'

Resposta

{
  "data": {
    "SUN": {
      "set_default_positions": null,
      "set_hindu_rising": null
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

Capturada de uma chamada real, com exatamente a requisição acima. Os resultados ficam em data, sob cada chave que você pediu.

Erros

Erros de consumo de créditos retornam { "error": "…", "message": "<code>", "is_error": true }. Mostre error para o usuário e use message para decidir o que fazer no código. Consulte a referência de erros.