POST/api/astro/eclipse/visibility-path/1 crédito

Trajetória de visibilidade do eclipse

Onde um eclipse solar é total, como uma linha de coordenadas que você pode desenhar em um mapa. Encontra o próximo eclipse solar a partir do momento informado, amostra o ponto em que o eixo da sombra da Lua encontra a Terra e retorna pares ordenados de latitude/longitude. No eclipse total de 2026-08-12, essa trajetória sai do Ártico siberiano, passa sobre o polo, desce pela Islândia e segue para o Atlântico, ao largo da Península Ibérica — é essa trajetória que define se um local vê um eclipse total ou parcial. A janela amostrada é a totalidade (ou a anularidade), não o eclipse inteiro. Fora dela, o eixo da sombra não atinge a Terra e não há linha central; por isso, um eclipse puramente parcial retorna uma trajetória vazia, com path_traced_over definido como "none", em vez de uma linha que não existe. Os pontos em que o eixo não atinge a Terra são descartados, então sample_count pode ser menor que o número de amostras pedido. Também retorna o ponto de eclipse máximo com magnitude, obscurecimento, série Saros e número de membro — o identificador que indexa os catálogos de eclipses. Os horários da trajetória estão em UTC, com o sufixo Z. Como a trajetória atravessa o globo, o deslocamento usado pelos demais endpoints de eclipse seria enganoso para um ponto do outro lado do mundo. Os limites das bordas da umbra e da penumbra não são retornados: neste cálculo, só a linha central é computada, e informar as posições vazias significaria publicar 0N 0E como limite.

https://api.occultapi.com/api/astro/eclipse/visibility-path/

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
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.
centrality	string	opcional	Central significa que o eixo da sombra da Lua realmente toca a Terra. Só faz sentido quando eclipse_type não é 'any'. `anycentralnon-central`
direction	string	opcional	Direção da busca a partir de date_time: para a frente ou para trás. `afterbefore`
eclipse_type	string	opcional	Restrinja a busca a um tipo de eclipse solar. `anytotalannularpartialhybrid`
elevation	number (double)	opcional
keys	array	opcional	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.
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.
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.
samples	integer	opcional	Número de pontos ao longo da trajetória. Quanto mais pontos, mais suave a linha; no máximo 120. min 2 · max 120
timezone_as_float	number (double)	opcional	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

Exemplo de requisição

curl -X POST https://api.occultapi.com/api/astro/eclipse/visibility-path/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2026-01-01T00:00:00+00:00","timezone_as_float":0,"eclipse_type":"total","direction":"after","samples":24}'

Resposta

{
  "data": {
    "found": true,
    "eclipse": {
      "type": "total",
      "centrality": "central",
      "maximum": "2026-08-12T17:45:57Z",
      "times": {
        "maximum": "2026-08-12T17:45:57Z",
        "local_apparent_noon": "2026-08-12T17:03:51Z",
        "begin": "2026-08-12T15:34:30Z",
        "end": "2026-08-12T19:57:57Z",
        "totality_begin": "2026-08-12T16:58:05Z",
        "totality_end": "2026-08-12T18:34:00Z",
        "centre_line_begin": "2026-08-12T17:00:06Z",
        "centre_line_end": "2026-08-12T18:32:01Z"
      }
    },
    "path_traced_over": "totality",
    "requested_samples": 24,
    "sample_count": 25,
    "path": [
      {
        "datetime_utc": "2026-08-12T16:58:05Z",
        "latitude": 74.877805,
        "longitude": 117.671955
      },
      {
        "datetime_utc": "2026-08-12T17:02:04Z",
        "latitude": 82.361743,
        "longitude": 112.418144
      },
      {
        "datetime_utc": "2026-08-12T17:06:04Z",
        "latitude": 87.329632,
        "longitude": 80.477549
      },
      {
        "datetime_utc": "2026-08-12T17:10:04Z",
        "latitude": 86.790315,
        "longitude": -2.537547
      },
      {
        "datetime_utc": "2026-08-12T17:14:04Z",
        "latitude": 83.870696,
        "longitude": -21.42455
      },
      {
        "datetime_utc": "2026-08-12T17:18:03Z",
        "latitude": 81.057681,
        "longitude": -26.067301
      },
      {
        "datetime_utc": "2026-08-12T17:22:03Z",
        "latitude": 78.429119,
        "longitude": -27.559629
      },
      {
        "datetime_utc": "2026-08-12T17:26:03Z",
        "latitude": 75.963829,
        "longitude": -27.916291
      },
      {
        "datetime_utc": "2026-08-12T17:30:03Z",
        "latitude": 73.627499,
        "longitude": -27.753208
      },
      {
        "datetime_utc": "2026-08-12T17:34:03Z",
        "latitude": 71.393131,
        "longitude": -27.30956
      },
      {
        "datetime_utc": "2026-08-12T17:38:02Z",
        "latitude": 69.248567,
        "longitude": -26.695107
      },
      {
        "datetime_utc": "2026-08-12T17:42:02Z",
        "latitude": 67.159166,
        "longitude": -25.955597
      },
      {
        "datetime_utc": "2026-08-12T17:46:02Z",
        "latitude": 65.120178,
        "longitude": -25.117197
      },
      {
        "datetime_utc": "2026-08-12T17:50:02Z",
        "latitude": 63.119601,
        "longitude": -24.188769
      },
      {
        "datetime_utc": "2026-08-12T17:54:02Z",
        "latitude": 61.146536,
        "longitude": -23.169557
      },
      {
        "datetime_utc": "2026-08-12T17:58:01Z",
        "latitude": 59.19864,
        "longitude": -22.056292
      },
      {
        "datetime_utc": "2026-08-12T18:02:01Z",
        "latitude": 57.248921,
        "longitude": -20.82451
      },
      {
        "datetime_utc": "2026-08-12T18:06:01Z",
        "latitude": 55.293732,
        "longitude": -19.455163
      },
      {
        "datetime_utc": "2026-08-12T18:10:01Z",
        "latitude": 53.318925,
        "longitude": -17.9132
      },
      {
        "datetime_utc": "2026-08-12T18:14:01Z",
        "latitude": 51.305904,
        "longitude": -16.145189
      },
      {
        "datetime_utc": "2026-08-12T18:18:00Z",
        "latitude": 49.236237,
        "longitude": -14.074018
      },
      {
        "datetime_utc": "2026-08-12T18:22:00Z",
        "latitude": 47.046663,
        "longitude": -11.526755
      },
      {
        "datetime_utc": "2026-08-12T18:26:00Z",
        "latitude": 44.648895,
        "longitude": -8.169827
      },
      {
        "datetime_utc": "2026-08-12T18:30:00Z",
        "latitude": 41.718798,
        "longitude": -2.829804
      },
      {
        "datetime_utc": "2026-08-12T18:34:00Z",
        "latitude": 37.795826,
        "longitude": 4.632462
      }
    ],
    "greatest_eclipse": {
      "datetime_utc": "2026-08-12T17:45:57Z",
      "latitude": 65.162226,
      "longitude": -25.135594,
      "attributes": {
        "solar_diameter_fraction_covered": 1.0177529811525174,
        "lunar_to_solar_diameter_ratio": 1.0395246462080372,
        "obscuration": 1.0806114900739452,
        "core_shadow_diameter_km": -132.45861086856522,
        "sun_azimuth": 68.50274145564674,
        "sun_true_altitude": 25.738278484149753,
        "sun_apparent_altitude": 25.771879784684916,
        "moon_elongation": 0.0010572200151275264,
        "magnitude_nasa": 1.0395246462080372,
        "saros_series": 126,
        "saros_member": 48
      },
      "saros": {
        "series": 126,
        "member": 48
      }
    },
    "notes": {
      "path": "Sampled evenly across totality. Times are UTC.",
      "limits": "Umbra and penumbra limits are unavailable: only the central line is computed for this calculation."
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

Capturada de uma chamada real, com exatamente a requisição acima. Os resultados ficam em data.

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.