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

Trajectoire de visibilité d’une éclipse

Les lieux où une éclipse de Soleil est totale, sous forme de ligne de coordonnées à tracer sur une carte. Trouve la prochaine éclipse de Soleil à partir du moment indiqué, échantillonne le point où l’axe de l’ombre de la Lune rencontre la Terre, puis renvoie des paires latitude/longitude ordonnées. Pour l’éclipse totale du 2026-08-12, cette trajectoire part de l’Arctique sibérien, passe au-dessus du pôle, descend sur l’Islande et sort dans l’Atlantique au large de la péninsule Ibérique — c’est elle qui détermine si un lieu voit une éclipse totale ou partielle. La plage échantillonnée est la totalité (ou l’annularité), et non l’éclipse entière. En dehors, l’axe de l’ombre manque complètement la Terre et il n’y a pas de ligne de centralité : une éclipse purement partielle renvoie donc une trajectoire vide, avec path_traced_over à "none", plutôt qu’une ligne qui n’existe pas. Les points où l’axe manque la Terre sont écartés : sample_count peut donc être inférieur au nombre d’échantillons demandé. Renvoie aussi le point de plus grande éclipse avec sa magnitude, son obscuration, sa série de Saros et son numéro de membre — l’identifiant qui sert d’index aux catalogues d’éclipses. Les heures de la trajectoire sont en UTC, avec le suffixe Z. Une trajectoire traverse le globe : le décalage qu’utilisent les autres endpoints d’éclipse serait trompeur pour un point situé à l’autre bout du monde. Les limites de l’ombre et de la pénombre ne sont pas renvoyées : ce calcul ne détermine que la ligne de centralité, et renvoyer les emplacements vides reviendrait à publier 0N 0E comme limite.

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

Tester la requête

Authentification

Envoyez votre clé dans l’en-tête X-API-Key. Une clé est un identifiant côté serveur : ne la placez jamais dans du JavaScript exécuté par le navigateur ni dans une application mobile.

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

Champs de la requête

Champ	Type	Obligatoire	Remarques
date_time	string (date-time)	obligatoire	Le moment du calcul, en ISO 8601. Incluez TOUJOURS un décalage ou un Z final - une valeur sans fuseau est lue comme Asia/Kolkata (UTC+05:30), et non comme UTC, et peut renvoyer le résultat de la veille avec un statut 200. '2026-09-01T06:00:00Z' et '2026-09-01 06:00:00' sont des instants différents et donnent des réponses différentes.
centrality	string	facultatif	Centrale signifie que l’axe de l’ombre de la Lune touche réellement la Terre. N’a de sens que lorsque eclipse_type n’est pas 'any'. `anycentralnon-central`
direction	string	facultatif	Rechercher vers l’avant à partir de date_time, ou vers l’arrière. `afterbefore`
eclipse_type	string	facultatif	Limiter la recherche à un seul type d’éclipse de Soleil. `anytotalannularpartialhybrid`
elevation	number (double)	facultatif
keys	array	facultatif	Les calculs à renvoyer, sous forme de liste de noms. Consultez le tableau des clés de cet endpoint ; un nom non reconnu fait rejeter toute la requête. Un appel coûte un crédit quel que soit le nombre de clés demandées : demandez donc tout ce dont vous avez besoin en une seule fois plutôt que de faire plusieurs appels.
latitude	number (double)	facultatif	Latitude du lieu, en degrés décimaux. Positive au nord, négative au sud. Exemple : 26.9124 pour Jaipur, 40.7128 pour New York. Les minutes et les secondes ne sont pas acceptées - convertissez d’abord.
longitude	number (double)	facultatif	Longitude du lieu, en degrés décimaux. Positive à l’est, négative à l’ouest. Exemple : 75.7873 pour Jaipur, -74.0060 pour New York. Attention au signe : sans le moins, New York se retrouve en Chine.
samples	integer	facultatif	Nombre de points à tracer le long de la trajectoire. Plus il est élevé, plus le tracé est lisse ; 120 au maximum. min 2 · max 120
timezone_as_float	number (double)	facultatif	Décalage UTC du lieu, en heures, sous forme décimale. Exemple : 5.5 pour l’Inde (UTC+05:30), -5 pour New York en hiver, 5.75 pour le Népal. Cette valeur n’est PAS contrôlée par rapport à date_time - si les deux divergent, vous obtenez une réponse réussie pour le mauvais moment ; tirez donc les deux de la même source. Utilisez le décalage en vigueur à cette date, pas celui d’aujourd’hui : une naissance en été dans un pays qui applique l’heure d’été exige le décalage d’été. min -12 · max 14

Exemple de requête

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

Réponse

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

Réponse capturée lors d’un vrai appel, avec exactement la requête ci-dessus. Les résultats se trouvent dans data.

Erreurs

Les erreurs du contrôle de clé et de crédits renvoient { "error": "…", "message": "<code>", "is_error": true }. Affichez error à vos utilisateurs et basez votre logique sur message. Voir la référence des erreurs.