/api/astro/eclipse/visibility-path/1 creditEclipse visibility path
Where a solar eclipse is total, as a line of coordinates you can draw on a map. Finds the next solar eclipse from the moment you give, then samples the point where the Moon's shadow axis meets the Earth and returns ordered latitude/longitude pairs. For the 2026-08-12 total that track runs out of the Siberian Arctic, over the pole, down across Iceland and out into the Atlantic off Iberia — the path that decides whether a place sees a total eclipse or a partial one. The window sampled is totality (or annularity), not the whole eclipse. Outside it the shadow axis misses the Earth altogether and there is no central line, so a purely partial eclipse returns an empty path with path_traced_over set to "none" rather than a line that does not exist. Points where the axis misses are dropped, so sample_count can be lower than the samples you asked for. Also returns the point of greatest eclipse with its magnitude, obscuration and Saros series and member number — the identifier eclipse catalogues are indexed by. Path times are UTC and suffixed Z. A track crosses the globe, so the offset the rest of the eclipse endpoints use would be misleading on a point halfway round the world from you. Umbra and penumbra edge limits are not returned: swisseph populates only the central line for this calculation, and reporting the empty slots would mean publishing 0N 0E as a boundary.
https://yogataraapi.prahlad.app/api/astro/eclipse/visibility-path/Authentication
Send your key in the X-API-Key header. Keys are server-side credentials — never put one in browser JavaScript or a mobile app.
X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/jsonRequest fields
| Field | Type | Required | Notes |
|---|---|---|---|
| date_time | string (date-time) | required | The moment to calculate for, ISO 8601. ALWAYS include an offset or a trailing Z - a value with no zone is read as Asia/Kolkata (UTC+05:30), not UTC, and can return the previous day's result with a 200. '2026-09-01T06:00:00Z' and '2026-09-01 06:00:00' are different instants and give different answers. |
| centrality | string | optional | Central means the Moon's shadow axis actually touches the Earth. Only meaningful when eclipse_type is not 'any'. anycentralnon-central |
| direction | string | optional | Search forward from date_time, or backward. afterbefore |
| eclipse_type | string | optional | Restrict the search to one kind of solar eclipse. anytotalannularpartialhybrid |
| elevation | number (double) | optional | |
| keys | array | optional | Which calculations to return, as a list of names. See the key table for this endpoint; an unrecognised name rejects the whole request. One call costs one credit however many keys you ask for, so request everything you need at once rather than making several calls. |
| latitude | number (double) | optional | Latitude of the place, in decimal degrees. Positive is north, negative is south. Example: 26.9124 for Jaipur, 40.7128 for New York. Minutes and seconds are not accepted - convert first. |
| longitude | number (double) | optional | Longitude of the place, in decimal degrees. Positive is east, negative is west. Example: 75.7873 for Jaipur, -74.0060 for New York. Note the sign: a missing minus puts New York in China. |
| samples | integer | optional | How many points to trace along the path. More is smoother; at most 120. min 2 · max 120 |
| timezone_as_float | number (double) | optional | UTC offset of the place, in hours, as a decimal. Example: 5.5 for India (UTC+05:30), -5 for New York in winter, 5.75 for Nepal. This is NOT validated against date_time - if the two disagree you get a successful response for the wrong moment, so derive both from the same source. Use the offset in force on that date, not today's: a summer birth in a country with daylight saving needs the summer offset. min -12 · max 14 |
Example request
curl -X POST https://yogataraapi.prahlad.app/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}'Response
{
"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: swisseph returns only the central line for this calculation."
}
},
"status": 200,
"is_error": false,
"message": "successful"
}Captured from a real call using the exact request above. Results sit under data.
Errors
Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.