qibla/.wiki/API-Reference.md

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.

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.

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.

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]].

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.

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.

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

---

Types

CompassAbbr

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

CompassName

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

---

Home | Architecture