Local Circumstances

Calculate the local circumstances of an eclipse for an observer

This API is available on the Starter plan or higher

The timing and characteristics of the key events (contact times) varies based on an observer's location. The 'local circumstances' represent what an observer at a given location will (weather permitting) be able to observe.

The local-circumstances end point calculates:

  • C1: First contact, the start of the partial eclipse phase

  • C2: Second contact, the start of the total eclipse (or annularity in the case of annular eclipses)

  • Max eclipse: the instant of greatest eclipse

  • C3: Third contact, the end of totality or annularity

  • C4: Fourth contact, the end of the partial eclipse

C2 and C3 do not occur for partial eclipses. Not all observers will observe all events.

C2 and C3 contact times are not adjusted for the effects of the lunar limb. Uneveness in the profile of the Moon's limb can result in changes in standard contact times of a few seconds or even tens of second in some circumstances (e.g. for locations near the edge of the path of totality/annularity).

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/local-circumstances/details/[JULIAN_DAY]",
	"params": {
		"apiKey": [YOUR_API_KEY],
		"obs": "[LAT,LNG,HEIGHT]"
	},
	"headers": {
		"Accept-Encoding": "deflate, gzip, br"
	}
})

Or, using curl:

curl "https://api.radiantdrift.com/solar-eclipse/local-circumstances/details/[JULIAN_DAY]?apiKey=[YOUR_API_KEY]y&obs=[LAT,LNG,HEIGHT]" \
     -H 'Accept-Encoding: deflate, gzip, br'

If no elements are available for the given JULIAN_DAY, a 404 Not Found response is given.

Example request

The following request obtains the local circumstances of the eclipse of Apr 8 2024 for an observer located in Mazatlan, Mexico, in the path of totality:

GET https://api.radiantdrift.com/solar-eclipse/local-circumstances/details/2460408.5?apiKey=[YOUR_API_KEY]&obs=23.2494,-106.4111,6

The expected response is as follows:

{
  "query": {
    "name": "solar-eclipse/local-circumstances/details",
    "jd": 2460408.5,
    "obs": {
      "lat": 23.2494,
      "lng": -106.4111,
      "height": 6
    },
    "elements": {
      "tMax": 2460409.26284,
      "t0": 18,
      "dT": 69.1,
      "x": [
        -0.31824401,
        0.5117116,
        0.0000326,
        -0.00000842
      ],
      "y": [
        0.21976399,
        0.2709589,
        -0.0000595,
        -0.00000466
      ],
      "d": [
        7.58620024,
        0.014844,
        -0.000002,
        0
      ],
      "l1": [
        0.53581399,
        0.0000618,
        -0.0000128,
        0
      ],
      "l2": [
        -0.010272,
        0.0000615,
        -0.0000127,
        0
      ],
      "mu": [
        89.59121704,
        15.00407982,
        0,
        0
      ],
      "tanF1": 0.0046683,
      "tanF2": 0.004645,
      "latGreatestEclipse": 25.3,
      "lngGreatestEclipse": -104.1
    }
  },
  "response": {
    "type": 8,
    "magnitude": 1.02094111,
    "contacts": [
      {
        "contact": 1,
        "key": "solar_eclipse_first_contact",
        "circumstances": {
          "t": -1.12283699,
          "x": -0.8927597,
          "xʹ": 0.51160654,
          "y": -0.0845471,
          "yʹ": 0.27107489,
          "d": 7.56953033,
          "sinD": 0.13172925,
          "cosD": 0.99128573,
          "dʹ": 0.01484849,
          "μ": 72.74408127,
          "μʹ": 15.00407982,
          "l1": 0.53572846,
          "l2": -0.01035707,
          "θ": -33.95572368,
          "θrad": -0.59263918,
          "cosθ": 0.82946945,
          "ξ": -0.5134634,
          "η": 0.28843316,
          "ζ": 0.8075434,
          "ξʹ": 0.19967925,
          "ηʹ": -0.01792172,
          "u": -0.3792963,
          "v": -0.37298026,
          "uʹ": 0.31192729,
          "vʹ": 0.28899661,
          "m": 0.53195861,
          "n": 0.42522662,
          "L1": 0.53195861,
          "L2": -0.01410811,
          "D": -0.2261029,
          "Δ": 0.01582068,
          "ψ1": 0.02974483,
          "ψ2": null,
          "f1": 0.00466827,
          "f2": 0.00464497,
          "ΔTcorrection": 0.00503885,
          "ρcosΦʹ": 0.91927577,
          "ρsinΦʹ": 0.39229676,
          "contact": 1
        },
        "observational": {
          "magnitude": 0,
          "obscuration": 0,
          "angularSeparation": 0.54705233,
          "sunAzAlt": {
            "azimuth": 110.18555172,
            "altitude": 53.84977956
          },
          "moonAzAlt": {
            "azimuth": 111.08044948,
            "altitude": 53.99663169
          },
          "sunSemidiameter": 0.26617147,
          "moonSemidiameter": 0.28088085,
          "moonDistance": 354503.87833613,
          "P": 225.48103852,
          "C": 299.54650213,
          "V": 74.06546362
        },
        "date": "2024-04-08T16:51:28.736Z"
      },
      {
        "contact": 2,
        "key": "solar_eclipse_second_contact",
        "circumstances": {
          "t": 0.14453601,
          "x": -0.2442826,
          "xʹ": 0.5117205,
          "y": 0.25892605,
          "yʹ": 0.27094141,
          "d": 7.58834569,
          "sinD": 0.13205477,
          "cosD": 0.99124242,
          "dʹ": 0.01484342,
          "μ": 91.75984683,
          "μʹ": 15.00407982,
          "l1": 0.53582265,
          "l2": -0.01026338,
          "θ": -14.93995812,
          "θrad": -0.26075146,
          "cosθ": 0.96619652,
          "ξ": -0.23699544,
          "η": 0.27157,
          "ζ": 0.93222722,
          "ξʹ": 0.23259374,
          "ηʹ": -0.00843711,
          "u": -0.00728717,
          "v": -0.01264395,
          "uʹ": 0.27912676,
          "vʹ": 0.27937852,
          "m": 0.01459357,
          "n": 0.39492291,
          "L1": 0.53147074,
          "L2": -0.01459357,
          "D": -0.00556649,
          "Δ": 0.00378147,
          "ψ1": 0.00711516,
          "ψ2": -0.26210965,
          "f1": 0.00466827,
          "f2": 0.00464497,
          "ΔTcorrection": 0.00503885,
          "ρcosΦʹ": 0.91927577,
          "ρsinΦʹ": 0.39229676,
          "contact": 2
        },
        "observational": {
          "magnitude": 1,
          "obscuration": 1,
          "angularSeparation": 0.01503645,
          "sunAzAlt": {
            "azimuth": 135.13101636,
            "altitude": 68.76281369
          },
          "moonAzAlt": {
            "azimuth": 135.17020821,
            "altitude": 68.75786285
          },
          "sunSemidiameter": 0.26617266,
          "moonSemidiameter": 0.28142289,
          "moonDistance": 353837.29855401,
          "P": 29.95639567,
          "C": 319.16166223,
          "V": 289.20526656
        },
        "date": "2024-04-08T18:07:31.279Z"
      },
      {
        "contact": 0,
        "key": "sun_max_eclipse_time_local",
        "circumstances": {
          "t": 0.18025921,
          "x": -0.22600227,
          "xʹ": 0.51172253,
          "y": 0.26860487,
          "yʹ": 0.27093699,
          "d": 7.58887594,
          "sinD": 0.13206394,
          "cosD": 0.9912412,
          "dʹ": 0.01484328,
          "μ": 92.29584058,
          "μʹ": 15.00407982,
          "l1": 0.53582471,
          "l2": -0.01026133,
          "θ": -14.40396437,
          "θrad": -0.2513966,
          "cosθ": 0.96856595,
          "ξ": -0.2286762,
          "η": 0.27127372,
          "ζ": 0.93438882,
          "ξʹ": 0.23316413,
          "ηʹ": -0.00815053,
          "u": 0.00267392,
          "v": -0.00266885,
          "uʹ": 0.2785584,
          "vʹ": 0.27908752,
          "m": 0.00377792,
          "n": 0.39431539,
          "L1": 0.53146271,
          "L2": -0.01460156,
          "D": 0,
          "Δ": 0.00377792,
          "ψ1": 0.00710858,
          "ψ2": -0.26171099,
          "f1": 0.00466827,
          "f2": 0.00464497,
          "ΔTcorrection": 0.00503885,
          "ρcosΦʹ": 0.91927577,
          "ρsinΦʹ": 0.39229676,
          "contact": 0
        },
        "observational": {
          "magnitude": 1.02094111,
          "obscuration": 1,
          "angularSeparation": 0.00389269,
          "sunAzAlt": {
            "azimuth": 136.25653606,
            "altitude": 69.10721832
          },
          "moonAzAlt": {
            "azimuth": 136.25554776,
            "altitude": 69.10334163
          },
          "sunSemidiameter": 0.26617268,
          "moonSemidiameter": 0.28143163,
          "moonDistance": 353826.32547418,
          "P": 134.94563484,
          "C": 320.14128192,
          "V": 185.19564708
        },
        "date": "2024-04-08T18:09:39.883Z"
      },
      {
        "contact": 3,
        "key": "solar_eclipse_third_contact",
        "circumstances": {
          "t": 0.21607801,
          "x": -0.20767295,
          "xʹ": 0.51172451,
          "y": 0.27830942,
          "yʹ": 0.27093253,
          "d": 7.58940761,
          "sinD": 0.13207314,
          "cosD": 0.99123997,
          "dʹ": 0.01484314,
          "μ": 92.83326868,
          "μʹ": 15.00407982,
          "l1": 0.53582675,
          "l2": -0.0102593,
          "θ": -13.86653628,
          "θrad": -0.24201671,
          "cosθ": 0.97085662,
          "ξ": -0.2203146,
          "η": 0.27098694,
          "ζ": 0.93647865,
          "ξʹ": 0.23371557,
          "ηʹ": -0.00786242,
          "u": 0.01264165,
          "v": 0.00732249,
          "uʹ": 0.27800894,
          "vʹ": 0.27879496,
          "m": 0.01460925,
          "n": 0.3937202,
          "L1": 0.53145498,
          "L2": -0.01460925,
          "D": 0.00555596,
          "Δ": 0.00378114,
          "ψ1": 0.00711475,
          "ψ2": -0.26179848,
          "f1": 0.00466827,
          "f2": 0.00464497,
          "ΔTcorrection": 0.00503885,
          "ρcosΦʹ": 0.91927577,
          "ρsinΦʹ": 0.39229676,
          "contact": 3
        },
        "observational": {
          "magnitude": 1,
          "obscuration": 1,
          "angularSeparation": 0.01505352,
          "sunAzAlt": {
            "azimuth": 137.41964248,
            "altitude": 69.44542616
          },
          "moonAzAlt": {
            "azimuth": 137.37727188,
            "altitude": 69.44312819
          },
          "sunSemidiameter": 0.2661727,
          "moonSemidiameter": 0.28144002,
          "moonDistance": 353815.7729215,
          "P": 239.91906605,
          "C": 321.15825633,
          "V": 81.23919028
        },
        "date": "2024-04-08T18:11:48.830Z"
      },
      {
        "contact": 4,
        "key": "solar_eclipse_fourth_contact",
        "circumstances": {
          "t": 1.55597623,
          "x": 0.47801428,
          "xʹ": 0.51175189,
          "y": 0.64120799,
          "yʹ": 0.27073989,
          "d": 7.60929231,
          "sinD": 0.13241715,
          "cosD": 0.99119408,
          "dʹ": 0.01483778,
          "μ": 112.93720862,
          "μʹ": 15.00407982,
          "l1": 0.53587916,
          "l2": -0.01020705,
          "θ": 6.23740366,
          "θrad": 0.10886323,
          "cosθ": 0.99408025,
          "ξ": 0.09987778,
          "η": 0.26783495,
          "ζ": 0.95773356,
          "ξʹ": 0.23930622,
          "ηʹ": 0.00321536,
          "u": 0.37813651,
          "v": 0.37337304,
          "uʹ": 0.27244567,
          "vʹ": 0.26752454,
          "m": 0.53140817,
          "n": 0.38183245,
          "L1": 0.53140817,
          "L2": -0.01465573,
          "D": 0.2029081,
          "Δ": -0.00147466,
          "ψ1": -0.00277502,
          "ψ2": 0.10079094,
          "f1": 0.00466827,
          "f2": 0.00464497,
          "ΔTcorrection": 0.00503885,
          "ρcosΦʹ": 0.91927577,
          "ρsinΦʹ": 0.39229676,
          "contact": 4
        },
        "observational": {
          "magnitude": 0,
          "obscuration": 0,
          "angularSeparation": 0.5476507,
          "sunAzAlt": {
            "azimuth": 201.94357928,
            "altitude": 73.25347858
          },
          "moonAzAlt": {
            "azimuth": 201.11359596,
            "altitude": 73.74781739
          },
          "sunSemidiameter": 0.26617281,
          "moonSemidiameter": 0.28147788,
          "moonDistance": 353751.88377885,
          "P": 45.36316599,
          "C": 20.26891699,
          "V": 334.90575101
        },
        "date": "2024-04-08T19:32:12.464Z"
      }
    ]
  }
}

The query object includes all parameters used for the calculation, including a copy of the Besselian elements, which may be useful for reference and comparison with results from other sources.

The response object includes some general properties of the eclipse, including its type and greatest magnitude (see below), and an array of contacts.

Response fields

Type

The type field is a numeric enum value that characterizes the eclipse. This value is applicable to the global circumstances of the eclipse, rather than specific to the local observer.

Values are defined as:

/**
 * See https://en.wikipedia.org/wiki/Solar_eclipse - Terminology for central eclipse
 * See https://eclipse.gsfc.nasa.gov/SEhelp/SEglossary.html - particularly for non-central eclipses
 * SolarNonCentral may represent a Non-central total, annular or hybrid eclipse 
 * @enum {number} EclipseType 
 */
export enum EclipseType {
  None = 0,
  LunarPenumbral,
  LunarPartial,
  LunarTotal,
  SolarPartial,
  SolarNonCentral,
  SolarCentralAnnular,
  SolarCentralHybrid,
  SolarCentralTotal
}

Magnitude

The magnitude is the ratio to the Sun's diameter of the straight line segment passing through the centers of the discs of the Sun and Moon and having the Sun's limb that is nearest to the Moon's center and the Moon's limb that is nearest to the Sun's center as its endpoints.

  • For a partial eclipse, magnitude is > 0.0 and < 1.0

  • For a total eclipse, at C2 and C3, magnitude = 1.0 and at the time of greatest eclipse, magnitude is > 1.0

  • For an annular eclipse, magnitude is always < 1.0

Contacts

The contactsfield contains an array of 0 to 4 objects representing the contact times calculated for the event and observer.

  • If no eclipse is visible, there will be no contacts given

  • For a partial only eclipse, only C1, greatest eclipse, and C4 will be returned

  • For a total, annular, or hybrid (e.g. annular-total, or annular-total-annular, total-annular) eclipse, all contacts C1, C2, C3, C4 and the details of greatest eclipse (which occurs between C2 and C3) will be returned

Each contact is classified using a numeric enum value in the contact property, where the values are as follows:

enum SolarEclipseContact {
  Greatest,  // 0
  C1,        // 1
  C2,        // 2
  C3,        // 3
  C4         // 4
}

While the moment 'greatest eclipse' does not strictly speaking represent a 'contact' (i.e. a limb of the Moon tangent to a limb of the Sun), it is convenient to consider this instant in the same context as the formal contact times.

Additionally, a descriptive key string property identifies each entry in the contacts array, e.g. solar_eclipse_fourth_contact.

Date

The date field contains the time at which the contact is calculated to occur for the observer. Remember that these are local circumstances - if you repeat the call for a different latitude or longitude, you'll get different answers. (If you keep the same latitude or longitude, but vary only the observer height above sea level, you'll get very slightly different answers.)

Circumstances

The circumstancesfield contains a number of numerical quantities used during the course of calculation. These can be used to verify calculation steps or to derive additional results.

Many of these values will be familiar to those who have performed their own eclipse calculations. We hope to document these more fully in the future. Please contact us if you have any specific questions.

Observational

The observational field contains a number of values that more fully describe the observational circumstances of the contact for the observer. For example, these values can be used to construct a simple graphical visualization of the local circumstances of the eclipse at key moments.

The sub-fields are as shown:

type Degrees = number;
type AzimuthFromNorth = Degrees;

interface LocalHorizontalCoordinates {
  azimuth: AzimuthFromNorth;
  altitude: Degrees;
}

type ObservationalCircumstances = {
  magnitude: number; // unitless, instantaneous magnitude (see definition above)
  obscuration: number; // unitless, fractional area of the Sun's disc that is obscured by the Moon
  angularSeparation: Degrees; // angular separation between the centers of Sun and Moon
  sunAzAlt: LocalHorizontalCoordinates;
  moonAzAlt: LocalHorizontalCoordinates;
  sunSemidiameter: Degrees;
  moonSemidiameter: Degrees;
  moonDistance: number; // in kilometres
  P: Degrees; // position angle of a point of contact, measured eastwards from north point of the solar limb
  C: Degrees; // parallactic angle,
  V: Degrees; // position angle of a point of contact, measured eastwards from the vertex of the solar limb (where the vertex point of the solar limb lies on a great circle arc drawn from the zenith to the center of the solar disk - i.e. the "top" of the sun for the viewer)
}

PreviousBesselian ElementsNextEclipse Paths

Last updated