# Local Circumstances {% hint style="info" %} This API is available on the **Starter** plan or higher {% endhint %} 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 {% hint style="info" %} C2 and C3 do not occur for partial eclipses. Not all observers will observe all events. {% endhint %} {% hint style="info" %} 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). {% endhint %} ### 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/local-circumstances/details/[JULIAN_DAY]", "params": { "apiKey": [YOUR_API_KEY], "obs": "[LAT,LNG,HEIGHT]" }, "headers": { "Accept-Encoding": "deflate, gzip, br" } }) ``` {% endcode %} Or, using `curl`: {% code overflow="wrap" lineNumbers="true" %} ```bash 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' ``` {% endcode %} 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: {% code overflow="wrap" %} ``` GET https://api.radiantdrift.com/solar-eclipse/local-circumstances/details/2460408.5?apiKey=[YOUR_API_KEY]&obs=23.2494,-106.4111,6 ``` {% endcode %} The expected response is as follows: {% code overflow="wrap" lineNumbers="true" %} ```json5 { "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" } ] } } ``` {% endcode %} 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: {% code overflow="wrap" lineNumbers="true" %} ```typescript /** * 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 } ``` {% endcode %} #### 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 `contacts`field 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: {% code overflow="wrap" lineNumbers="true" %} ```typescript enum SolarEclipseContact { Greatest, // 0 C1, // 1 C2, // 2 C3, // 3 C4 // 4 } ``` {% endcode %} {% hint style="info" %} 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. {% endhint %} 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 `circumstances`field 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. {% hint style="info" %} 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. {% endhint %} #### 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: {% code overflow="wrap" lineNumbers="true" %} ```typescript 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) } ``` {% endcode %} --- # 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/local-circumstances.md?ask= ``` 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.