Eclipse Paths

Eclipse paths suitable for use on digital maps

This API is available on the Pro plan or higher

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.

The solar-eclipse/path end point returns GeoJSON 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:

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

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'

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

Request options

Parameter	Default value	Description
JULIAN_DAY	None	Required. Midnight UTC of the date of the eclipse, expressed as a Julian Day.
SPACING_FACTOR	1	Optional. 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.
PATH_OPTIONS	c	Optional. A comma separated list of eclipse path line types. Supported values are: c: central path tn: northern limit of total eclipse ts: southern limit of total eclipse pn: northern limit of partial eclipse ps: southern limit of partial eclipse eqn: northern lines of equal magnitude eqs: southern lines of equal magnitude e.g. c,tn,ts,pn,psdenotes the central path, northern limit of totality, southern limit of totality, northern limit of partial eclipse, southern limit of partial eclipse.
LINES_OF_EQUAL_MAG	0	Optional. If PATH_OPTIONS includes eqn and/or eqs this value controls how many lines of equal magnitude are calculated. For example, PATH_OPTIONS='eqn' and LINES_OF_EQUAL_MAG=1, the returned path will return the northern limit of equal magnitude, for mag = 0.5.
MIN_SUN_ALT	0°	Optional. 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 SPACING_FACTOR values. If the observer is high above the surrounding terrain (e.g. in an aircraft) such that there is a positive dip of the horizon, a negative value may be used to extend the eclipse path for observations near sunrise or sunset, adjusted for elevation above the horizon. Note: results may be unpredictable due to lack of convergence of the underlying interpolation logic.
POLY_OPTIONS	None	Optional. A comma-separated list of three PATH_OPTION 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. tn,c,ts. The end points of the second (central) path are used together with the north/south limits to determine the bounds of the calculated polygon

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):

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

When displayed on a map the output appears as shown:

The Total Eclipse of Apr 20 2023, displayed using geojson.io

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:

Path of totality corssing the Exmouth peninsula in Western Australia. April 20 2023.

Known Issues

There are no known issues affecting the central path and path of totality for the upcoming Oct 14 2023 and Apr 8 2024 eclipses.

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.