qibla/.github/wiki/Home.md

@acamarata/qibla

Qibla direction, great-circle path, and haversine distance. Pure math, zero dependencies.

Pages

• API Reference: Full function and constant reference
• Architecture: Algorithm design, spherical trigonometry, implementation decisions

What It Does

This library computes three things:

1. Qibla bearing: the initial compass bearing from any point on Earth to the Ka'bah in Mecca, using the forward azimuth formula from spherical trigonometry
2. Great-circle path: a series of waypoints along the geodesic from origin to Ka'bah, suitable for rendering on a map
3. Haversine distance: the surface distance between two coordinate pairs using the haversine formula

All calculations use a spherical Earth model (WGS-84 volumetric mean radius, 6,371 km). The Ka'bah coordinates (21.422511°N, 39.82615°E) are sourced from verified GPS data.

Quick Start

npm install @acamarata/qibla

import {
  qiblaAngle,
  compassDir,
  distanceKm,
  KAABA_LAT,
  KAABA_LNG,
} from "@acamarata/qibla";

const bearing = qiblaAngle(40.7128, -74.006); // New York
console.log(bearing); // ~58.48
console.log(compassDir(bearing)); // "NE"

const km = distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG);
console.log(km); // ~9,634

Installation

npm install @acamarata/qibla
# or
pnpm add @acamarata/qibla
# or
yarn add @acamarata/qibla

Related Packages

• pray-calc: Islamic prayer times
• nrel-spa: NREL Solar Position Algorithm
• moon-sighting: Lunar crescent visibility

---

API Reference | Architecture