Qibla direction, great-circle path, and haversine distance. Pure math, zero dependencies.
npm install @acamarata/qiblaimport {
qiblaAngle,
compassDir,
distanceKm,
KAABA_LAT,
KAABA_LNG,
} from "@acamarata/qibla";
// Bearing from New York to the Ka'bah
const bearing = qiblaAngle(40.7128, -74.006);
console.log(bearing); // ~58.48
console.log(compassDir(bearing)); // "NE"
// Distance in kilometers
const km = distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG);
console.log(km); // ~9,634Computes the initial bearing (forward azimuth) from the given coordinates to the Ka'bah.
| Parameter | Type | Description |
|---|---|---|
lat |
number |
Latitude in decimal degrees (-90 to 90) |
lng |
number |
Longitude in decimal degrees (-180 to 180) |
| Returns | number |
Bearing in degrees clockwise from north (0-360) |
Throws RangeError if coordinates are out of bounds.
Eight-point compass abbreviation: N, NE, E, SE, S, SW, W, NW.
Full compass name: North, Northeast, East, Southeast, South, Southwest, West, Northwest.
Generates waypoints along the great circle from [lat, lng] to the Ka'bah using spherical linear interpolation (Slerp). Returns steps + 1 points (default: 121).
Useful for drawing Qibla direction lines on maps.
Haversine distance between two points in kilometers (spherical Earth approximation, R = 6,371 km).
| Name | Value | Description |
|---|---|---|
KAABA_LAT |
21.422511 | Ka'bah center latitude (degrees north) |
KAABA_LNG |
39.826150 | Ka'bah center longitude (degrees east) |
EARTH_RADIUS_KM |
6371 | WGS-84 volumetric mean radius |
All calculations use the forward azimuth formula from spherical trigonometry. Great-circle paths use Slerp (spherical linear interpolation). Distance uses the haversine formula. The Ka'bah coordinates are fixed constants from verified GPS data.
See Architecture for algorithm details.
Node.js 20+. Works in browsers and all major bundlers (Webpack, Vite, Rollup, esbuild). Ships as dual CJS/ESM with full TypeScript definitions.
import { qiblaAngle, CompassAbbr, CompassName } from "@acamarata/qibla";
const bearing: number = qiblaAngle(40.7128, -74.006);Full reference available on the GitHub Wiki:
- Home: Overview and quick start
- API Reference: Full function and constant reference
- Architecture: Algorithm design, spherical trigonometry, Slerp implementation
- pray-calc: Islamic prayer times calculator
- nrel-spa: NREL Solar Position Algorithm
- moon-sighting: Lunar crescent visibility
Ka'bah coordinates verified against published GPS surveys and cross-checked with satellite imagery. The forward azimuth formula follows the standard spherical trigonometry derivation used in aviation and geodesy.