# API Reference

## Functions

### `qiblaAngle(lat, lng)`

Computes the initial bearing from the given coordinates to the Ka'bah.

Uses the forward azimuth formula from spherical trigonometry:

```
θ = atan2(sin(Δλ)·cos(φ₂), cos(φ₁)·sin(φ₂) − sin(φ₁)·cos(φ₂)·cos(Δλ))
```

where φ₁, λ₁ is the observer and φ₂, λ₂ is the Ka'bah.

**Parameters:**

| Name  | Type     | Description                                |
| ----- | -------- | ------------------------------------------ |
| `lat` | `number` | Observer latitude in decimal degrees. Valid range: −90 to 90. |
| `lng` | `number` | Observer longitude in decimal degrees. Valid range: −180 to 180. |

**Returns:** `number` — Bearing in degrees clockwise from true north. Range: [0, 360).

**Throws:** `RangeError` if either coordinate is out of bounds.

```typescript
import { qiblaAngle } from '@acamarata/qibla';

qiblaAngle(40.7128, -74.006);   // ~58.48  (New York → Mecca)
qiblaAngle(51.5074, -0.1278);   // ~119.0  (London → Mecca)
qiblaAngle(35.6762, 139.6503);  // ~293.3  (Tokyo → Mecca)
```

---

### `compassDir(bearing)`

Returns the eight-point compass abbreviation for a bearing.

Maps the bearing to one of eight 45° sectors, selecting the nearest cardinal or intercardinal direction.

**Parameters:**

| Name      | Type     | Description                  |
| --------- | -------- | ---------------------------- |
| `bearing` | `number` | Bearing in degrees (0–360).  |

**Returns:** `CompassAbbr` — One of: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`.

```typescript
import { compassDir } from '@acamarata/qibla';

compassDir(0);    // "N"
compassDir(45);   // "NE"
compassDir(58.5); // "NE"
compassDir(270);  // "W"
```

---

### `compassName(bearing)`

Returns the full compass direction name for a bearing.

**Parameters:**

| Name      | Type     | Description                  |
| --------- | -------- | ---------------------------- |
| `bearing` | `number` | Bearing in degrees (0–360).  |

**Returns:** `CompassName` — One of: `North`, `Northeast`, `East`, `Southeast`, `South`, `Southwest`, `West`, `Northwest`.

```typescript
import { compassName } from '@acamarata/qibla';

compassName(58.5); // "Northeast"
```

---

### `qiblaGreatCircle(lat, lng, steps?)`

Generates waypoints along the great-circle geodesic from the observer to the Ka'bah, using the Slerp (spherical linear interpolation) formula.

Useful for drawing the Qibla direction line on a map. Returns `steps + 1` points uniformly spaced along the geodesic.

**Parameters:**

| Name    | Type     | Default | Description                                      |
| ------- | -------- | ------- | ------------------------------------------------ |
| `lat`   | `number` | —       | Observer latitude in decimal degrees (−90 to 90). |
| `lng`   | `number` | —       | Observer longitude in decimal degrees (−180 to 180). |
| `steps` | `number` | `120`   | Number of segments. Result has `steps + 1` points. |

**Returns:** `[number, number][]` — Array of `[latitude, longitude]` pairs in degrees.

**Throws:** `RangeError` if coordinates are out of bounds.

Special case: if the observer is at the Ka'bah (distance = 0), returns `[[lat, lng]]`.

```typescript
import { qiblaGreatCircle } from '@acamarata/qibla';

const path = qiblaGreatCircle(40.7128, -74.006); // 121 points
// path[0]  ≈ [40.7128, -74.006]   (New York)
// path[120] ≈ [21.42, 39.83]      (Ka'bah)
```

---

### `distanceKm(lat1, lng1, lat2, lng2)`

Haversine distance between two points in kilometers.

Uses the haversine formula with a spherical Earth (R = 6,371 km, WGS-84 volumetric mean). Accurate to within 0.5% globally.

**Parameters:**

| Name   | Type     | Description                           |
| ------ | -------- | ------------------------------------- |
| `lat1` | `number` | First point latitude in decimal degrees.  |
| `lng1` | `number` | First point longitude in decimal degrees. |
| `lat2` | `number` | Second point latitude in decimal degrees. |
| `lng2` | `number` | Second point longitude in decimal degrees. |

**Returns:** `number` — Distance in kilometers.

```typescript
import { distanceKm, KAABA_LAT, KAABA_LNG } from '@acamarata/qibla';

distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG); // ~9,634 km
```

---

## Constants

| Constant          | Value       | Description                                         |
| ----------------- | ----------- | --------------------------------------------------- |
| `KAABA_LAT`       | `21.422511` | Ka'bah center latitude in decimal degrees north.    |
| `KAABA_LNG`       | `39.82615`  | Ka'bah center longitude in decimal degrees east.    |
| `EARTH_RADIUS_KM` | `6371`      | WGS-84 volumetric mean radius in kilometers.        |

```typescript
import { KAABA_LAT, KAABA_LNG, EARTH_RADIUS_KM } from '@acamarata/qibla';
```

---

## Types

### `CompassAbbr`

```typescript
type CompassAbbr = 'N' | 'NE' | 'E' | 'SE' | 'S' | 'SW' | 'W' | 'NW';
```

### `CompassName`

```typescript
type CompassName =
  | 'North' | 'Northeast' | 'East' | 'Southeast'
  | 'South' | 'Southwest' | 'West' | 'Northwest';
```

---

[Home](Home) | [Architecture](Architecture)