api.radiantdrift.com
  • Radiant Drift API
    • Subscription Plans
    • Educational Use and Research
    • API End Points
  • Getting Started
    • About your account
    • Request Authentication
    • Managing API Keys
    • OpenAPI Specification
    • Date/Time Format
    • Validity, Accuracy, and Precision
  • Usage Guidelines
    • Acceptable Use Policy
    • Usage Credits and Call Costs
    • Attribution
    • Rate Limits
  • Julian Day
  • Delta-T
  • Rise, Transit, Set Times
  • Body Position
    • Request Parameters
    • Position at a given time
    • Positions for a time range
    • Observer location
  • Solar Eclipses
    • Embeddable Web Widgets
      • Eclipse Map
      • Eclipse Simulator
    • Besselian Elements
    • Local Circumstances
    • Eclipse Paths
    • Five Millennium Canon of Solar Eclipses
  • The Moon
    • Lunar Libration
    • Lunar Limb Profile
  • Geospatial
    • Geodesic
    • Elevation
  • Reference
    • Definitions
    • Errors
Powered by GitBook
On this page
  • Request format
  • Example
  • Fields
  1. Solar Eclipses

Five Millennium Canon of Solar Eclipses

Key data from NASA's solar eclipse catalog queryable as JSON

PreviousEclipse PathsNextThe Moon

Last updated 1 year ago

NASA's Five Millennium Canon of Solar Eclipses provides details of all solar eclipses occurring over the period -1999 to +3000 (2000 BCE to 3000 CE). This public domain data is available at .

An extract of this data - specifically the summary data for each solar eclipse - is available via a web service.

Acknowledgement:

  • Eclipse Predictions by Fred Espenak, NASA's GSFC,

Request format

Request eclipses between a start and end year as follows:

axios({
	"method": "GET",
	"url": "https://api.radiantdrift.com/solar-eclipse/catalog/[YEAR_FROM]/[YEAR_TO]",
	"params": {
		"apiKey": [YOUR_API_KEY],
		["saros": [SAROS_CYCLE],]
		["primaryType": [ECLIPSE_TYPE]]
	},
	"headers": {
		"Accept-Encoding": "deflate, gzip, br",
		"Cache-Control": "max-age=86400"
	}
})
curl "https://api.radiantdrift.com/solar-eclipse/catalog/1000/2500?apiKey=[YOUR_API_KEY][&saros=[SAROS_CYCLE]][&primaryType=[ECLIPSE_TYPE]]" \
     -H 'Accept-Encoding: deflate, gzip, br' \
     -H 'Cache-Control: max-age=86400'
  • P Partial Eclipse

  • A Annular Eclipse

  • T Total Eclipse

  • H Hybrid or Annular/Total Eclipse

Example

The following request returns the Hybrid eclipses in Saros cycle 137 between the years 1000 and 2500:

GET https://api.radiantdrift.com/solar-eclipse/catalog/1000/2500?saros=137&primaryType=H

The expected response is as follows (abbreviated for length):

{
  "query": {
    "name": "solar-eclipse/catalog/1000/2500",
    "yearFrom": 1000,
    "yearTo": 2500,
    "credit": "Eclipse Predictions by Fred Espenak, NASA's GSFC",
    "eclipseType": "H",
    "saros": "137"
  },
  "response": [
    {
      "catalog": 8821,
      "year": 1713,
      "month": "Dec",
      "day": 17,
      "greatestTD": 0.669675926,
      "deltaT": 9,
      "lunation": -3538,
      "saros": 137,
      "eclipseType": "H",
      "qle": "p-",
      "gamma": 0.7249,
      "mag": 1.0094,
      "sLat": "23N",
      "sLng": "65W",
      "sunAlt": 43,
      "pathWidthKM": "47",
      "sCentralDuration": "00m56s",
      "lat": 23,
      "lng": -65,
      "centraDurationSec": 56,
      "isoDate": "1713-12-17T00:00:00Z",
      "eclipseTypeQualifier": null,
      "eclipseTypePrimary": "H",
      "countryISO": null,
      "mrgID": 1912,
      "tzID": "Etc/GMT+4"
    },
    {
      "catalog": 8867,
      "year": 1731,
      "month": "Dec",
      "day": 29,
      "greatestTD": 0.03255787,
      "deltaT": 11,
      "lunation": -3315,
      "saros": 137,
      "eclipseType": "H",
...
  ]
}

In this case, the array included in the response property conforms to the following Typescript type:

export type FiveMCSERecord = {
  catalog: number;
  year: number;
  month: string;
  day: number;
  greatestTD: number;
  deltaT: number;
  lunation: number;
  saros: number;
  eclipseType: string;
  qle: string;
  gamma: number;
  mag: number;
  sLat: string;
  sLng: string;
  sunAlt: number;
  pathWidthKM: string | null;
  sCentralDuration: string | null;
  lat: number;
  lng: number;
  centraDurationSec: number;
  isoDate: string;
  eclipseTypeQualifier: string | null;
  eclipseTypePrimary: string;
  countryISO: string | null;
  mrgID: number | null;
  tzID: string;
}

Fields

Field
Type
Comments

sLat

string

NASA's Lat. field in text form

sLng

string

NASA's Long. field in text form

sCentralDuration

string

NASA's Central Dur. field in text form

lat

number

Latitude of greatest eclipse in degrees, positive north, to nearest whole degree

lng

number

Longitude of greatest eclipse in degrees, positive east, to nearest whole degree

centraDurationSec

number

Duration of totality or annularity at location of greatest eclipse, in seconds

isoDate

string

Midnight of date of eclipse in ISO Date format. Gregorian Calendar is used for dates after 1582 Oct 15. Julian Calendar is used for dates before 1582 Oct 04.

eclipseTypeQualifier

string | null

The second character of NASA's Ecl. Type field.

eclipseTypePrimary

string

The first character of NASA's Ecl. Type field. These are broken out separately for indexing and data querying efficiency reasons.

countryISO

string | null

2-letter ISO country code corresponding the modern day country at the lat/lng of the point of greatest eclipse. Null if point does not lie within a country.

mrgID

number | null

tzID

string

The modern Time Zone ID corresponding to the point of greatest eclipse.

You can optionally specify a number and/or an eclipse type, where valid eclipse types are:

Except as noted below, the fields returned in the response correspond directly to the source NASA data, except that field names are camel-cased. Please refer to the for details.

numeric ID corresponding to the sea or ocean at the lat/lng of the point of greatest eclipse. Null if the point lies over land. This field and the countryISO field are useful for general characterization of the location of greatest eclipse in user interfaces.

5MCSE
NASA/Goddard Space Flight Center
Saros cycle
Key to Catalog of Solar Eclipses
Marine Resources