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.

2KB

ReadMe.txt

Kaguya for Eclipses ReadMe.txt, courtesy of David Herald.

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

Parameter	Default value	Description
DATE_TIME	None	Optional. The date/time for which the limb profile is desired. Required if LIBRATION_IN_LNG and LIBRATION_IN_LATare omitted.
LAT,LNG	None	Optional. The observer's latitude and longitude (geodetic). Required if LIBRATION_IN_LNG and LIBRATION_IN_LATare omitted.
LIBRATION_IN_LNG, LIBRATION_IN_LAT	None	Optional. Libration values to be used. Ignored if observer LAT,LNG and DATE_TIME are given. Required otherwise. See above note on supported range of values.
FORMAT	json	Optional. If omitted, API returns a JSON response. Supported values: json (default) or svg (scalable vector graphics).
EXAGGERATION_FACTOR	20	Optional. Ignored unless FORMAT is svg. Applies a vertical exaggeration factor to the lunar limb data when requesting SVG format. Larger values
SIZE	1000	Optional. Ignored unless FORMAT is svg. Sets height and width of returned SVG object. Valid range: 1.0 to 10000.0.

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:

SVG showing lunar limb with 15x vertical exaggeration factor

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:

SVG with styling applied

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:

SVG for arbitrary libration values, 30x vertical exaggeration