qibla/.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