GET /v1/eclipses/solar — Find upcoming or past solar eclipses, globally or at a specific location.

Solar Eclipses

Search for solar eclipses from a given start date. Returns global eclipse data by default, or location-specific data (including magnitude and obscuration) when observer coordinates are provided.

Text

GET  /v1/eclipses/solar
POST /v1/eclipses/solar

Credit cost: 3

Parameters

Parameter	Type	Required	Default	Description
`datetime`	string	One of `datetime` or `jd`	—	ISO 8601 UTC datetime
`jd`	number	One of `datetime` or `jd`	—	Julian Day in UT1
`lat`	number	No	—	Observer latitude (enables local mode with magnitude/obscuration)
`lon`	number	No	—	Observer longitude
`alt`	number	No	0	Observer altitude in meters
`type`	string	No	all	Filter by eclipse type: `total`, `annular`, `partial`, `annular_total` (comma-separated)
`backward`	boolean	No	`false`	Search backward in time
`count`	integer	No	1	Number of results to return (1–10)

Response

Global mode (no lat/lon)

JSON

{
  "data": [
    {
      "eclipse_type": "total",
      "maximum": {
        "jd": 2460409.261,
        "datetime": "2024-04-08T18:16:00.000Z"
      },
      "first_contact": { "jd": 2460409.175, "datetime": "2024-04-08T16:12:00.000Z" },
      "second_contact": { "jd": 2460409.245, "datetime": "2024-04-08T17:53:00.000Z" },
      "third_contact": { "jd": 2460409.277, "datetime": "2024-04-08T18:39:00.000Z" },
      "fourth_contact": { "jd": 2460409.347, "datetime": "2024-04-08T20:20:00.000Z" }
    }
  ],
  "meta": { "..." }
}

Local mode (with lat/lon)

When observer coordinates are provided, the response includes magnitude and obscuration:

JSON

{
  "data": [
    {
      "eclipse_type": "partial",
      "maximum": { "jd": 2460409.261, "datetime": "2024-04-08T18:16:00.000Z" },
      "first_contact": { "jd": 2460409.205, "datetime": "2024-04-08T16:55:00.000Z" },
      "fourth_contact": { "jd": 2460409.317, "datetime": "2024-04-08T19:37:00.000Z" },
      "magnitude": 0.923,
      "obscuration": 0.891
    }
  ],
  "meta": { "..." }
}

Field	Type	Description
`eclipse_type`	string	`total`, `annular`, `partial`, or `annular_total`
`maximum`	object	Time of greatest eclipse (`jd` and `datetime`)
`first_contact`	object	First contact (partial eclipse begins)
`second_contact`	object	Totality/annularity begins (null for partial eclipses)
`third_contact`	object	Totality/annularity ends (null for partial eclipses)
`fourth_contact`	object	Last contact (partial eclipse ends)
`magnitude`	number	Fraction of solar diameter covered (local mode only)
`obscuration`	number	Fraction of solar disc area covered (local mode only)

Examples

Next global solar eclipse

Bash

curl "https://api.morphemeris.com/v1/eclipses/solar?datetime=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/eclipses/solar?datetime=2024-01-01T00:00:00Z",
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.morphemeris.com/v1/eclipses/solar",
    params={"datetime": "2024-01-01T00:00:00Z"},
    headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()

Eclipse visible from New York

Bash

curl "https://api.morphemeris.com/v1/eclipses/solar?datetime=2024-01-01T00:00:00Z&lat=40.7128&lon=-74.006" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

Next 5 total solar eclipses

Bash

curl "https://api.morphemeris.com/v1/eclipses/solar?datetime=2024-01-01T00:00:00Z&type=total&count=5" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

Solar Eclipses

On this page