POST/api/astro/eclipse/visibility-path/1 кредит

Полоса видимости затмения

Где солнечное затмение полное — в виде линии координат, которую можно нарисовать на карте. Находит ближайшее солнечное затмение от заданного момента, затем последовательно вычисляет точку, где ось тени Луны встречается с Землёй, и возвращает упорядоченные пары широта/долгота. Для полного затмения 2026-08-12 эта полоса выходит из сибирской Арктики, проходит через полюс, спускается через Исландию и уходит в Атлантику у Пиренейского полуострова. Именно эта полоса определяет, увидят ли в том или ином месте полное затмение или частное. Точки берутся в пределах полной (или кольцеобразной) фазы, а не всего затмения. Вне её ось тени вообще не попадает на Землю и центральной линии нет, поэтому для чисто частного затмения возвращается пустая полоса с path_traced_over = "none", а не несуществующая линия. Точки, где ось проходит мимо Земли, отбрасываются, поэтому sample_count может оказаться меньше запрошенного числа точек. Также возвращается точка наибольшей фазы затмения с её величиной, покрытием диска, серией сарос и номером в ней — идентификатором, по которому индексируются каталоги затмений. Моменты для полосы даются в UTC с суффиксом Z. Полоса пересекает земной шар, и смещение, которое используют остальные эндпоинты затмений, вводило бы в заблуждение для точки на другой стороне планеты. Границы тени и полутени не возвращаются: в этом расчёте вычисляется только центральная линия, а если выводить пустые значения, границей оказалась бы точка 0N 0E.

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

Попробовать запрос

Аутентификация

Передавайте ключ в заголовке X-API-Key. Ключ — это серверные учётные данные: никогда не вставляйте его в JavaScript на стороне браузера или в мобильное приложение.

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

Поля запроса

Поле	Тип	Обязательно	Примечания
date_time	string (date-time)	обязательный	Момент расчёта в формате ISO 8601. ВСЕГДА указывайте смещение или суффикс Z: значение без часового пояса интерпретируется как Asia/Kolkata (UTC+05:30), а не UTC, и может вернуть результат за предыдущий день со статусом 200. '2026-09-01T06:00:00Z' и '2026-09-01 06:00:00' — разные моменты, и ответы для них будут разными.
centrality	string	необязательный	«Центральное» означает, что ось тени Луны действительно касается Земли. Имеет смысл, только если eclipse_type не равно 'any'. `anycentralnon-central`
direction	string	необязательный	Искать вперёд от date_time или назад. `afterbefore`
eclipse_type	string	необязательный	Ограничить поиск одним видом солнечного затмения. `anytotalannularpartialhybrid`
elevation	number (double)	необязательный
keys	array	необязательный	Какие расчёты вернуть — списком названий. См. таблицу ключей этого эндпоинта; нераспознанное название отклоняет весь запрос. Один вызов стоит один кредит, сколько бы ключей вы ни запросили, поэтому запрашивайте всё нужное сразу, а не несколькими вызовами.
latitude	number (double)	необязательный	Широта места в десятичных градусах. Положительные значения — север, отрицательные — юг. Пример: 26.9124 для Джайпура, 40.7128 для Нью-Йорка. Минуты и секунды не принимаются — сначала переведите значение в десятичные градусы.
longitude	number (double)	необязательный	Долгота места в десятичных градусах. Положительные значения — восток, отрицательные — запад. Пример: 75.7873 для Джайпура, -74.0060 для Нью-Йорка. Следите за знаком: без минуса Нью-Йорк окажется в Китае.
samples	integer	необязательный	Сколько точек рассчитать вдоль полосы. Чем больше, тем плавнее линия; не более 120. min 2 · max 120
timezone_as_float	number (double)	необязательный	Смещение UTC для места, в часах, десятичным числом. Пример: 5.5 для Индии (UTC+05:30), -5 для Нью-Йорка зимой, 5.75 для Непала. Оно НЕ сверяется с date_time: если значения расходятся, вы получите успешный ответ для неверного момента, поэтому берите оба из одного источника. Используйте смещение, действовавшее на эту дату, а не сегодняшнее: для рождения летом в стране с летним временем нужно летнее смещение. min -12 · max 14

Пример запроса

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

Ответ

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

Записано с реального вызова ровно с этим запросом. Результаты лежат в data.

Ошибки

Ошибки списания кредитов приходят в виде { "error": "…", "message": "<code>", "is_error": true }. Людям показывайте error, а логику стройте на message. Подробнее — в справочнике ошибок.