Lunar Limb Profile

Lunar limb profile data for solar eclipse calculations

Last updated 5 months ago

Lunar Limb Profile

Lunar limb profile data for solar eclipse calculations

This API is available on the Pro plan or higher

The lunar-limb end point returns a limited set of data related to the lunar limb profile. This is commonly used in making advanced solar eclipse calculations (specifically to find adjusted times and position angles of the second and third contacts), and to aid in simulating the appearance of Baily's Beads.

Credit:

The data returned by this API is from data derived from the Kaguya mission by David Herald. Please review the ReadMe.txt file linked below for additional information.

Lunar limb profiles are available only for a limited range of libration values:

l, libration in longitude: +9.0° to -9.0°
b, libration in latitude: +1.6° to -1.6°
Resolution: 0.2° intervals

These libration values cover the ranges which occur during solar eclipses (when the Moon is always near one of its nodes). The resolution of 0.2° is sufficient for the purposes of establishing the effects of variation in the lunar limb on solar eclipse observations.

The API will return JSON data containing limb data for a given lunar libration. The desired lunar libration can be given directly, or alternatively it will be calculated from a given date. Additionally, the data can be requested in SVG form for graphical display, with a desired vertical exaggeration factor.

Request format

axios({
	"method": "GET",
	"url": "https://api.radiantdrift.com/lunar-limb/[DATE_TIME]",
	"params": {
		["obs": "[LAT,LNG]",]
		["l": "[LIBRATION_IN_LNG]",]
		["b": "[LIBRATION_IN_LAT]",]
		["format": [FORMAT],]
		["xf": [EXAGGERATION_FACTOR],]
		["size": [SIZE]]
	}
})

Request parameters

If the observer latitude and longitude are given, the API will calculate the topocentric libration values automatically. If observer location is omitted, you must supply valid values for libration in longitude and latitude within the ranges noted above.

If all cases, the given or inferred libration values are 'snapped' to the closest limb profile data set from the Kaguya/Herald source.

Example 1: JSON format

This example returns the lunar limb profile for the 2015 total eclipse as observed in Svalbard at the time of greatest eclipse:

GET 'https://api.radiantdrift.com/lunar-limb/2015-03-20T10:11:57.7Z?obs=78.22213,15.65047

The (excerpted) response is:

{
  "query": {
    "name": "lunar-limb",
    "date": "2015-03-20T10:11:57.700Z",
    "observer": {
      "lat": 78.22213,
      "lng": 15.65047
    },
    "l": 0.8740651392225147,
    "b": -0.25992041772556207,
    "P": 335.07397418464956,
    "filename": "0.8_-0.2_0.0_359.8_0.2.json"
  },
  "response": {
    "l": 0.8,
    "b": -0.2,
    "aa_from": 0,
    "aa_to": 359.8,
    "deg": 0.2,
    "data": [
      -0.28,
      -0.17,
      -0.21,
      -0.5,
      -0.57,
      -0.52,
      -0.49,
      -0.49,
      -0.12,
      -0.11,
      -0.32,
      -0.19,
      -0.09,
      -0.08,
      -0.09,
      -0.11,
      -0.12,
      -0.17,
      -0.29,
      -0.37,
      -0.3,
      -0.22,
      -0.21,
      -0.26,
      -0.11,
      …

The query object shows the parameters used to determine what limb profile data is required, including the topocentric libration values (l and b) and position angle (P) calculated for the given date and observer location.

The response object contains the rounded libration values used to select from the Kaguya/Herald dataset. aa_from and aa_to indicate the range of limb profile data point radial angles in degrees given in data. deg shows the resolution (always 0.2°).

The data property contains the array of raw limb offsets in arc seconds. E.g. the first value -0.28″ indicates that at the angle of 0° as measured from the center of mass of the Moon, the angular semi-diameter is reduced from the mean semi-diameter by -0.28″.

Be sure to consult the ReadMe.txt file linked above to understand how to relate these values to the reference values used in preparation of the dataset.

Example 2: SVG format

This example returns the lunar limb profile for the 2015 total eclipse as observed in Svalbard at the time of greatest eclipse in SVG format, with a vertical exaggeration factor of 15 and a size of 800:

GET 'https://api.radiantdrift.com/lunar-limb/2015-03-20T10:11:57.7Z?obs=78.22213,15.65047&format=svg&xf=15&size=800

The raw response is as follows (excerpt shown):

<svg height="800" width="800"><polygon points="483.90997,219.44624 483.42721,218.83305 482.74090,218.65999 481.72314,219.22229 480.99957,219.14363 480.43300,218.71497 479.83854,218.34697 479.20396,218.06939 479.03969,216.70113 478.41201,216.39676 477.50750,216.74632 477.02890,216.09118 476.50970,215.52629 475.87752,215.23059 475.21998,214.99665 474.54971,214.79489 473.89087,214.56568 473.18412,214.45850 472.39563,214.56374 471.65515,214.55220 471.08780,214.09289 470.52950,213.60520 469.88971,213.33001 469.18182,213.23801 468.69550,212.54462 468.20517,211.85235 467.67829,211.25207 467.02977,210.98666 466.39087,210.69312 465.61373,210.79683 464.97376,210.50810 464.55976,209.55131 463.89458,2…

The points returned at scaled based on the size parameter value and the position angle rotation (P in the JSON format example above) is already applied.

When displayed in graphical form, this SVG object appears like this - it has no styling included:

The SVG object can be styled for display in your own app or website using tools such as CSS or other graphical editing tools. For example, with green border and light grey fill:

Example 3: manually specified libration values

GET 'https://api.radiantdrift.com/lunar-limb/?l=7.2&b=-1.6&format=svg&xf=30&size=1000

The resulting SVG appears as shown:

PreviousLunar Libration NextGeospatial