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

Festivais hindus (calculados para um local)

Todos os festivais hindus de um ano civil, calculados do zero para o local que você informar, junto com os ekadashis e as observâncias jainistas, sikhs e cristãs que o motor acompanha. Ao contrário dos endpoints de calendários regionais, que retornam uma lista curada por tradição, este traz o conjunto pan-indiano completo, com a janela exata do tithi em cada entrada. O ano é percorrido tithi a tithi, e não dia a dia; assim, um tithi com menos de vinte e quatro horas não passa despercebido e um longo não é contado duas vezes. `moon_option` define como os meses lunares são nomeados: 'poornima' usa diretamente o mês purnimanta, enquanto qualquer outro valor — inclusive o próprio 'amavas' — usa o mês amanta e o converte, que é o que a maioria dos panchangs norte-indianos imprime. Envie `year`, `date_time` e o local. Como cada entrada traz o início e o fim do tithi regente, e não uma data única, você decide em que dia civil exibi-la; se preferir que a API decida, use um dos endpoints de calendários regionais, que atribuem cada observância ao dia em que ela é de fato observada.

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

Testar requisição

Dados de Festivais hindus (calculados para um local) exibidos numa interface — Os dados deste endpoint exibidos numa interface real. A API entrega os valores; o layout é você quem monta.

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
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. 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. `calculate_festivals` Array de strings; existe apenas uma chave.
latitude	number (double)	obrigatório	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)	obrigatório	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
moon_option	string	obrigatório	`amavaspoornima` Diferencia maiúsculas de minúsculas; em minúsculas. 'poornima' usa diretamente o mês lunar purnimanta; QUALQUER outro valor - inclusive o próprio 'amavas' e qualquer erro de digitação - segue o ramo else (mês amanta convertido para purnimanta), então erros de grafia se comportam silenciosamente como 'amavas'. Encaminhado em.
timezone_as_float	number (double)	obrigatório	Deslocamento UTC do local, em horas, como número decimal. Exemplo: 5.5 para a Índia (UTC+05:30), -5 para Nova York no inverno, 5.75 para o Nepal. Este valor NÃO é conferido com date_time: se os dois divergirem, você recebe uma resposta bem-sucedida para o momento errado. Por isso, tire os dois da mesma fonte. Use o deslocamento em vigor naquela data, não o de hoje: quem nasceu no verão, em um país com horário de verão, precisa do deslocamento de verão. min -12 · max 14
year	integer	obrigatório	Ano de nascimento como número, por exemplo 1990. Quatro dígitos.

Chaves disponíveis (1)

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
calculate_festivals	year	As observâncias do ano inteiro, como um objeto com cinco listas: `festivals`, `ekadashis`, `jain_festivals`, `sikh_festivals` e `christian_festivals`. Cada entrada traz o nome do festival, o `start` e o `end` do tithi regente como strings de timestamp UTC e o `month` lunar; as entradas de ekadashi trazem também o `paksha`. Recebe `year`.

Exemplo de requisição

curl -X POST https://api.occultapi.com/api/astro/festival/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys":["calculate_festivals"],"moon_option":"amavas","year":2025,"date_time":"2025-02-12T08:35:00.795Z","latitude":26.9124,"longitude":75.7873,"timezone_as_float":5.5}'

Resposta

{
  "_truncated": true,
  "_note": "Response shortened for the catalogue.",
  "preview": "{\"data\": {\"calculate_festivals\": {\"festivals\": [{\"festival\": \"Guru Govind singh Jayanti\", \"start\": \"2025-01-05 14:46:25 UTC\", \"end\": \"2025-01-06 12:54:41 UTC\", \"month\": \"Pausha\"}, {\"festival\": \"Samkata 4\", \"start\": \"2025-01-16 22:37:19 UTC\", \"end\": \"2025-01-18 00:01:19 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Sakat Chauth\", \"start\": \"2025-01-16 22:37:19 UTC\", \"end\": \"2025-01-18 00:01:19 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Ardhodaya Yoga\", \"start\": \"2025-01-28 14:07:08 UTC\", \"end\": \"2025-01-29 12:36:33 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Mahodaya Yoga\", \"start\": \"2025-01-28 14:07:08 UTC\", \"end\": \"2025-01-29 12:36:33 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Mauni Ama\", \"start\": \"2025-01-28 14:07:08 UTC\", \"end\": \"2025-01-29 12:36:33 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Mauni Amavas\", \"start\": \"2025-01-28 14:07:08 UTC\", \"end\": \"2025-01-29 12:36:33 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Gauri 3\", \"start\": \"2025-01-31 08:30:11 UTC\", \"end\": \"2025-02-01 06:09:21 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Gauri Tritiya\", \"start\": \"2025-01-31 08:30:11 UTC\", \"end\": \"2025-02-01 06:09:21 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Varada(Til) 4\", \"start\": \"2025-02-01 06:09:21 UTC\", \"end\": \"2025-02-02 03:45:30 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Varada Chaturthi\", \"start\": \"2025-02-01 06:09:21 UTC\", \"end\": \"2025-02-02 03:45:30 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Vasanta 5\", \"start\": \"2025-02-02 03:45:30 UTC\", \"end\": \"2025-02-03 01:23:48 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Shree 5\", \"start\": \"2025-02-02 03:45:30 UTC\", \"end\": \"2025-02-03 01:23:48 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Vasant Panchami\", \"start\": \"2025-02-02 03:45:30 UTC\", \"end\": \"2025-02-03 01:23:48 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Aarogya (Ratha) 7\", \"start\": \"2025-02-03 23:08:15 UTC\", \"end\": \"2025-02-04 21:01:48 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Ratha Saptami\", \"start\": \"2025-02-03 23:08:15 UTC\", \"end\": \"2025-02-04 21:01:48 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Bhishma 8\", \"start\": \"2025-02-04 21:01:48 UTC\", \"end\": \"2025-02-05 19:06:38 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Bhishma Ashtami\", \"start\": \"2025-02-04 21:01:48 UTC\", \"end\": \"2025-02-05 19:06:38 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Bhishma 12\", \"start\": \"2025-02-08 14:47:05 UTC\", \"end\": \"2025-02-09 13:56:25 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Bhishma Dvadashi\", \"start\": \"2025-02-08 14:47:05 UTC\", \"end\": \"2025-02-09 13:56:25 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Guru Ravidas Jayanti\", \"start\": \"2025-02-11 13:26:37 UTC\", \"end\": \"2025-02-12 13:54:03 UTC\", \"month\": \"Magha\"}, {\"festival\": \"Maha Shivaratri\", \"start\": \"2025-02-26 05:39:30 UTC\", \"end\": \"2025-02-27 03:25:42 UTC\", \"month\": \"Phalguna\"}, {\"festival\": \"Holashtaka begins\", \"start\": \"2025-03-06 05:21:59 UTC\", \"end\": \"2025-03-07 03:49:44 UTC\", \"month\": \"Phalguna\"}, {\"festival\": \"Holika Dahana\", \"start\": \"2025-03-13 05:07:03 UTC\", \"end\": \"2025-03-14 06:55:19 UTC\", \"month\": \"Phalguna\"}, {\"festival\": \"Chhoti Holi\", \"start\": \"2025-03-13 05:07:03 UTC\", \"end\": \"2025-03-14 06:55:19 UTC\", \"month\": \"Phalguna\"}, {\"festival\": \"Dhoolivandana\", \"start\": \"2025-03-14 06:55:19 UTC\", \"end\": \"2025-03-15 09:04:19 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Vasantotsava\", \"start\": \"2025-03-14 06:55:19 UTC\", \"end\": \"2025-03-15 09:04:19 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Holi\", \"start\": \"2025-03-14 06:55:19 UTC\", \"end\": \"2025-03-15 09:04:19 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Shitala Pujan\", \"start\": \"2025-03-21 22:54:58 UTC\", \"end\": \"2025-03-22 23:54:32 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Sheetala Ashtami\", \"start\": \"2025-03-21 22:54:58 UTC\", \"end\": \"2025-03-22 23:54:32 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Basoda\", \"start\": \"2025-03-21 22:54:58 UTC\", \"end\": \"2025-03-22 23:54:32 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Vaaruni yoga\", \"start\": \"2025-03-26 20:13:53 UTC\", \"end\": \"2025-03-27 17:34:30 UTC\", \"month\": \"Chaitra\"}, {\"festival\": \"Maha Vaaruni Yoga\", \"start\": \"2025-03-26 20:13:53 UTC\", \"end\": \"2025-03-27 17:34:30 UTC\", \"month\": \"Chaitra\"}, {\""
}

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.