# Eclipse Paths

{% hint style="info" %}
This API is available on the **Pro** plan or higher
{% endhint %}

{% hint style="warning" %}
Please note that solar eclipse path functionality is currently in **beta**. Please read Known Issues prior to use. These affect some paths which cross extreme latitudes and/or the anti-meridian.
{% endhint %}

The `solar-eclipse/path` end point returns [GeoJSON](https://geojson.org) representing the path of a solar eclipse. This data is suitable for display on digital maps or to derive your own geographic representations.

GeoJSON is a simple data format, somewhat similar to KML, used to represent geographic data structures. It is widely supported by map SDKs, including Leaflet and Google Maps.

### Request format

Given the midnight UTC on the date of the eclipse, converted to a Julian Day, the request is made as shown:

{% code overflow="wrap" lineNumbers="true" %}

```javascript
axios({
	"method": "GET",
	"url": "https://api.radiantdrift.com/solar-eclipse/path/[JULIAN_DAY]",
	"params": {
		"apiKey": "[YOUR_API_KEY]",
		["spacingFactor": "[SPACING_FACTOR]",]
		["paths": "[PATH_OPTIONS]",]
		["eqm": "[LINES_OF_EQUAL_MAG",]
		["minAlt": "[MIN_SUN_ALT]",]
		["poly": "[POLY_OPTIONS]"]
	},
	"headers": {
		"Accept-Encoding": "deflate, gzip, br"
	}
})
```

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

```bash
curl "https://api.radiantdrift.com/solar-eclipse/path/2460408.5?apiKey=[YOUR_API_KEY][&spacingFactor=[SPACING_FACTOR][&paths=[PATH_OPTIONS]][&eqm=[LINES_OF_EQUAL_MAG]][&minAlt=[MIN_SUN_ALT]][&poly=[POLY_OPTIONS]]" \
     -H 'Accept-Encoding: deflate, gzip, br'
```

{% endcode %}

All arguments are optional, with the exception of `JULIAN_DAY(`plus a valid Authorization method).

#### Request options

<table><thead><tr><th width="229">Parameter</th><th width="135">Default value</th><th>Description</th></tr></thead><tbody><tr><td><code>JULIAN_DAY</code></td><td>None</td><td><strong>Required</strong>. Midnight UTC of the date of the eclipse, expressed as a Julian Day.</td></tr><tr><td><code>SPACING_FACTOR</code></td><td>1</td><td><em>Optional</em>. Controls the  longitudinal spacing of path points. Max = 40. For example, SPACING_FACTOR=10 results in points spaced every 0.1°. 1 or even values are recommended.</td></tr><tr><td><code>PATH_OPTIONS</code></td><td><code>c</code></td><td><p><em>Optional</em>. A comma separated list of eclipse path line types. Supported values are:</p><ul><li><code>c</code>: central path</li><li><code>tn</code>: northern limit of total eclipse</li><li><code>ts</code>: southern limit of total eclipse</li><li><code>pn</code>: northern limit of partial eclipse</li><li><code>ps</code>: southern limit of partial eclipse</li><li><code>eqn</code>: northern lines of equal magnitude</li><li><code>eqs</code>: southern lines of equal magnitude</li></ul><p>e.g. <code>c,tn,ts,pn,ps</code>denotes the central path, northern limit of totality, southern limit of totality, northern limit of partial eclipse, southern limit of partial eclipse.</p></td></tr><tr><td><code>LINES_OF_EQUAL_MAG</code></td><td>0</td><td><em>Optional</em>. If <code>PATH_OPTIONS</code> includes <code>eqn</code> and/or <code>eqs</code> this value controls how many lines of equal magnitude are calculated. For example, <code>PATH_OPTIONS='eqn'</code> and <code>LINES_OF_EQUAL_MAG=1</code>, the returned path will return the northern limit of equal magnitude, for mag = 0.5.</td></tr><tr><td><code>MIN_SUN_ALT</code></td><td>0°</td><td><p><em>Optional</em>. The minimum true altitude of the Sun relative to the horizon for which path points will be included. The standard is zero degrees, but it may be advantageous to use a small negative value, particularly with lower <code>SPACING_FACTOR</code> values.<br><br>If the observer is high above the surrounding terrain (e.g. in an aircraft) such that there is a positive <a href="https://aty.sdsu.edu/explain/atmos_refr/dip.html">dip of the horizon</a>, a negative value may be used to extend the eclipse path for observations near sunrise or sunset, adjusted for elevation above the horizon.</p><p></p><p>Note: results may be unpredictable due to lack of convergence of the underlying interpolation logic.</p></td></tr><tr><td><code>POLY_OPTIONS</code></td><td>None</td><td><em>Optional.</em> A comma-separated list of three  <code>PATH_OPTION</code> values representing the northern, central and southern limits of a polygon to be returned in the GeoJSON output. Typical usage is to show the area of the path of totality/annularity, e.g. <code>tn,c,ts</code>. The end points of the second (central) path are used together with the north/south limits to determine the bounds of the calculated polygon</td></tr></tbody></table>

### Example request

The following request generates GeoJSON for the path of the Apr 20 2023, including the central path, limits of totality, limits of partial eclipse, and lines of equal eclipse magnitude (for mag=0.2, 0.4, 0.6, 0.8):

{% code overflow="wrap" %}

```
GET https://api.radiantdrift.com/solar-eclipse/path/2460054.5?spacingFactor=10&paths=c,tn,ts,pn,ps,eqn,eqs&eqm=4&minAlt=-0.27&poly=tn,c,ts
```

{% endcode %}

When displayed on a map the output appears as shown:

<figure><img src="https://1001599322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbA8iUHgJsg3uY5Dn2s3E%2Fuploads%2FV4tMXeGg6WbjE6AModJp%2Ftse2023-geojson.jpg?alt=media&#x26;token=6850aafe-0d7f-4b7c-86d2-1b25aef6bae7" alt=""><figcaption><p>The Total Eclipse of Apr 20 2023, displayed using <a href="https://geojson.io/#map=2.5/-7.49/128.63">geojson.io</a></p></figcaption></figure>

GeoJSON can generally be styled as desired by setting properties either directly in tools such as geojson.io, or using the styling capabilities of mapping SDKs. For example, this screenshot shows a close up of the path of totality as it crosses Exmouth, Western Australia, with the central path shown in green and the polygon representing the path of totality in pink:

<figure><img src="https://1001599322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbA8iUHgJsg3uY5Dn2s3E%2Fuploads%2FuIT07OwlrgNwtgLDh1RB%2Ftse2023-exmouth.jpg?alt=media&#x26;token=54b08c8e-e9c0-4c3d-b1c0-2e3ce5c0935c" alt=""><figcaption><p>Path of totality corssing the Exmouth peninsula in Western Australia. April 20 2023.</p></figcaption></figure>

### Known Issues

{% hint style="info" %}
There are **no known issues** affecting the central path and path of totality for the upcoming Oct 14 2023 and Apr 8 2024 eclipses.
{% endhint %}

Known issues for eclipse paths include:

* Northern or southern limits of partial eclipses, or lines of equal magnitude may be incomplete at extreme latitudes
* Eclipses where one or more lines cross the anti-meridian may exhibit inconsistent or incorrect anti-meridian crossing behavior
* Rarely, an eclipse path may include one or more 'rogue' points, arising from two sources:
  * Bad results of mathematical iteration (i.e. the underlying algorithm converges to an incorrect value under rare conditions) - these typically show up as single stray points that appear as a discontinuity in latitude
  * Zig-zagging due to incorrect merging of separate path segments between moderate and high latitudes
* Straight line segments, due to failure of the underlying algorithm to converge as expected. For example north of Siberia for the Aug 12 2026 eclipse.

This endpoint remains in beta while we work to resolve these issues. If you run into anything not mentioned above, please [let us know](mailto:support@radiantdrift.com).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.radiantdrift.com/solar-eclipses/eclipse-paths.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.