@qivam/client

Official TypeScript SDK for the Qivam API — mosque discovery, prayer times calculation, and qibla direction.

• Zero dependencies (native fetch)
• Full TypeScript types
• Works in Node.js 18+, browsers, and edge runtimes
• ESM only

Install

npm install @qivam/client

Quick Start

import { Qivam } from "@qivam/client";

const qivam = new Qivam({ apiKey: "qv_..." });

// Search mosques
const mosques = await qivam.mosques.list({ q: "central", country: "GB" });

// Calculate prayer times for any location
const times = await qivam.prayerTimes.calculate({
  latitude: 21.4225,
  longitude: 39.8262,
  method: "umm_al_qura",
});

// times.prayers.fajr    → "04:54"
// times.prayers.dhuhr   → "12:24"
// times.prayers.maghrib → "18:36"

Configuration

const qivam = new Qivam({
  apiKey: "qv_...",                          // Required
  baseUrl: "https://api.qivam.com",         // Optional (default)
  timeout: 30000,                            // Optional, milliseconds (default: 30s)
});

Mosques

// List mosques with filters
const result = await qivam.mosques.list({
  city: "London",
  country: "GB",
  facilities: ["parking", "womens_area"],
  source: "masjid-api",
  claim_status: "unclaimed",
  limit: 10,
});

// Full-text search
const search = await qivam.mosques.list({ q: "east london mosque" });

// Find nearby mosques
const nearby = await qivam.mosques.nearby({
  lat: 51.5074,
  lng: -0.1278,
  radius_km: 5,
});

// Get a single mosque by ID or slug
const mosque = await qivam.mosques.get("east-london-mosque");

Prayer Times

// Calculate for any coordinates (single day)
const times = await qivam.prayerTimes.calculate({
  latitude: 51.5074,
  longitude: -0.1278,
  method: "isna",
  madhab: "hanafi",
});

// Generate a full month (up to 30 days)
const month = await qivam.prayerTimes.calculate({
  latitude: 24.7136,
  longitude: 46.6753,
  method: "umm_al_qura",
  days: 30,
});

// Get supported calculation methods
const { data: methods } = await qivam.prayerTimes.getMethods();
// 21 methods: mwl, isna, umm_al_qura, diyanet, jakim, ...

// Get qibla direction
const qibla = await qivam.prayerTimes.getQibla({
  latitude: 40.7128,
  longitude: -74.0060,
});
// qibla.bearing  → 58.48
// qibla.distance → 9510 (km to Kaaba)

Supported Methods

mwl isna umm_al_qura egyptian karachi tehran jafari gulf kuwait qatar diyanet jakim muis kemenag tunisia algeria morocco france russia dubai jordan

Adjustments

Fine-tune any prayer time by +/- 30 minutes:

const times = await qivam.prayerTimes.calculate({
  latitude: 51.5074,
  longitude: -0.1278,
  method: "mwl",
  adjustments: { fajr: 2, isha: -1 },
});

Error Handling

import { QivamRateLimitError, QivamAuthError } from "@qivam/client";

try {
  const times = await qivam.prayerTimes.calculate({ ... });
} catch (error) {
  if (error instanceof QivamRateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof QivamAuthError) {
    console.log("Invalid API key");
  }
}

| Error | Status | When | |---|---|---| | QivamAuthError | 401/403 | Invalid or missing API key | | QivamValidationError | 400 | Invalid request parameters | | QivamNotFoundError | 404 | Resource not found | | QivamRateLimitError | 429 | Rate limit exceeded | | QivamError | Other | Any other HTTP error |

Get an API Key

Request a free API key at qivam.com.

License

See LICENSE.