# Lunar Limb Profile

{% hint style="info" %}
This API is available on the **Pro** plan or higher
{% endhint %}

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](https://en.wikipedia.org/wiki/Baily's_beads).

{% hint style="info" %}
Credit:

The data returned by this API is from data derived from the [Kaguya](https://en.wikipedia.org/wiki/SELENE) mission by **David Herald**. Please review the ReadMe.txt file linked below for additional information.
{% endhint %}

{% file src="<https://1001599322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbA8iUHgJsg3uY5Dn2s3E%2Fuploads%2F8D1Jk0I72GfVegG9eJKa%2FReadMe.txt?alt=media&token=c1cbae23-2597-4c00-9477-bd8e39fd11ec>" %}
Kaguya for Eclipses ReadMe.txt, courtesy of David Herald.
{% endfile %}

{% hint style="warning" %}
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.
{% endhint %}

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

<pre class="language-javascript" data-overflow="wrap" data-line-numbers><code class="lang-javascript">axios({
	"method": "GET",
	"url": "https://api.radiantdrift.com/lunar-limb/[DATE_TIME]",
<strong>	"params": {
</strong>		["obs": "[LAT,LNG]",]
		["l": "[LIBRATION_IN_LNG]",]
		["b": "[LIBRATION_IN_LAT]",]
		["format": [FORMAT],]
		["xf": [EXAGGERATION_FACTOR],]
		["size": [SIZE]]
	}
})
</code></pre>

### Request parameters

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

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:

{% code overflow="wrap" %}

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

{% endcode %}

The (excerpted) response is:

```json
{
  "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″.&#x20;

{% hint style="warning" %}
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.
{% endhint %}

### 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:

{% code overflow="wrap" %}

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

{% endcode %}

The raw response is as follows (excerpt shown):

{% code overflow="wrap" %}

```xml
<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…
```

{% endcode %}

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:

<figure><img src="https://1001599322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbA8iUHgJsg3uY5Dn2s3E%2Fuploads%2FJn3xLssp3gohCAdEc4x3%2Fimage.png?alt=media&#x26;token=b02cf24f-9f12-438e-b417-bbf4f2829b5f" alt="Image of lunar limb SVG"><figcaption><p>SVG showing lunar limb with 15x vertical exaggeration factor</p></figcaption></figure>

The SVG object can be styled for display in your own app or website using tools such as [CSS](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/SVG_and_CSS) or other graphical editing tools. For example, with green border and light grey fill:

<figure><img src="https://1001599322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbA8iUHgJsg3uY5Dn2s3E%2Fuploads%2FGOSKUOtciM2kLyS29Ov2%2Flunar-limb-example-styled.svg?alt=media&#x26;token=8a2b5f70-5de4-4803-8356-24099f6aee2e" alt="Styled SVG showing lunar limb"><figcaption><p>SVG with styling applied</p></figcaption></figure>

### Example 3: manually specified libration values

{% code overflow="wrap" %}

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

{% endcode %}

The resulting SVG appears as shown:

<figure><img src="https://1001599322-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbA8iUHgJsg3uY5Dn2s3E%2Fuploads%2FTkz3fKCIcV4C3iftHVNW%2Fimage.png?alt=media&#x26;token=a0a43c07-65c3-4051-9cef-71e972ec77b8" alt="SVG of lunar limb with 30x vertical exaggeration"><figcaption><p>SVG for arbitrary libration values, 30x vertical exaggeration</p></figcaption></figure>