Regional Guide

MENA Developer Quickstart & Regional Integration Guide

This guide is written for developers in the GCC and MENA region and addresses the five most common integration questions: authentication headers, regional latency, Islamic finance asset calculations, GCC holiday calendars, and Arabic/bilingual text support.

1. Correct ****** Authentication

Every KhaleejiAPI request requires an Authorization header using the Bearer scheme. The raw API key value alone is rejected with 401 Unauthorized.

bash
# ✅ Correct — ****** in Authorization header
curl -X GET "https://khaleejiapi.dev/api/v1/email/[email protected]" \
  -H "Authorization: ******"
 
# ❌ Wrong — raw key without ******
# Authorization: YOUR_API_KEY_HERE

Using the official SDK, the header is set automatically:

typescript
import { KhaleejiAPI } from "@khaleejiapi/sdk";
 
// The SDK sets Authorization: ****** automatically
const client = new KhaleejiAPI({ apiKey: process.env.KHALEEJI_API_KEY! });
 
const result = await client.validation.validateEmail({ email: "[email protected]" });
console.log(result.valid); // true

2. Regional Latency Expectations

KhaleejiAPI runs on AWS ap-south-1 (Mumbai) behind Cloudflare's global anycast network. GCC cities are 80–120 ms from the Mumbai origin over a typical broadband or data-centre connection. Cached responses served from the nearest Cloudflare PoP (Dubai, Riyadh, Doha, etc.) add only ~5 ms.

bash
# Typical round-trip latency from GCC cities to ap-south-1 (Mumbai)
# Dubai (UAE)         → ~80 ms
# Abu Dhabi (UAE)     → ~85 ms
# Riyadh (KSA)        → ~90 ms
# Jeddah (KSA)        → ~95 ms
# Doha (Qatar)        → ~80 ms
# Kuwait City         → ~85 ms
# Manama (Bahrain)    → ~80 ms
# Muscat (Oman)       → ~70 ms
#
# Cached responses (Cloudflare edge) add ~5 ms from nearest PoP.
# Use the /api/v1/health endpoint to measure live latency from your region:

Measure live latency from your server or CI environment:

bash
curl -w "\nConnect: %{time_connect}s  TTFB: %{time_starttransfer}s  Total: %{time_total}s\n" \
  -o /dev/null -s \
  "https://khaleejiapi.dev/api/v1/health"

3. Islamic Finance — Zakat Calculation with Live Gold / Silver Rates

The Zakat calculator fetches live gold and silver spot prices to determine the nisab threshold automatically. You supply asset values in any supported currency and choose whether to base the nisab on gold or silver.

bash
# Calculate Zakat on mixed assets — live gold/silver rates fetched automatically
curl -X POST "https://khaleejiapi.dev/api/v1/zakat/calculate" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": {
      "cash": 50000,
      "gold": 150,
      "silver": 500,
      "investments": 20000,
      "receivables": 5000
    },
    "currency": "AED",
    "nisabBasis": "gold"
  }'
 
# Response excerpt:
# {
#   "data": {
#     "zakatDue": 1875.00,
#     "nisabThreshold": 22450.00,
#     "goldRatePerGram": 299.33,
#     "silverRatePerGram": 3.12,
#     "eligible": true
#   }
# }

TypeScript SDK equivalent:

typescript
import { KhaleejiAPI } from "@khaleejiapi/sdk";
 
const client = new KhaleejiAPI({ apiKey: process.env.KHALEEJI_API_KEY! });
 
const result = await client.islamicFinance.calculateZakat({
  assets: {
    cash: 50_000,
    gold: 150,      // grams
    silver: 500,    // grams
    investments: 20_000,
    receivables: 5_000,
  },
  currency: "AED",
  nisabBasis: "gold",   // "gold" | "silver"
});
 
console.log(`Zakat due: ${result.zakatDue} ${result.currency}`);
console.log(`Eligible: ${result.eligible}`);
  • Supported currencies: AED, SAR, QAR, KWD, BHD, OMR, EGP, USD, EUR, GBP — exchange-rate conversion is applied automatically.
  • nisabBasis: "gold" (85 g gold) or "silver" (595 g silver). Gulf scholars most commonly use gold.
  • Other Islamic Finance APIs: Sukuk tracker (/api/v1/sukuk) and Takaful calculator (/api/v1/takaful) follow the same auth and response envelope pattern.

4. GCC Holiday Calendars & Business Days

GCC countries observe different weekend rules and national holidays. The calendar API is region-aware: Saudi Arabia's weekend is Friday–Saturday; the UAE (public and private sectors) moved to Saturday–Sunday in January 2022. Qatar, Kuwait, Bahrain, and Oman observe Friday–Saturday. All Islamic public holidays (Eid Al-Fitr, Eid Al-Adha, National Days, etc.) are included.

bash
# Check if today is a business day in the UAE
curl "https://khaleejiapi.dev/api/v1/calendar/business-day?country=AE&date=2025-01-01" \
  -H "Authorization: ******"
 
# Supported country codes: AE (UAE), SA (KSA), QA (Qatar), KW (Kuwait),
#                          BH (Bahrain), OM (Oman), EG (Egypt), JO (Jordan)
 
# Response:
# { "data": { "isBusinessDay": false, "holiday": "New Year's Day", "date": "2025-01-01" } }
bash
# Find the next business day after a date (skip weekends + GCC holidays)
curl "https://khaleejiapi.dev/api/v1/calendar/next-business-day?country=SA&date=2025-03-30" \
  -H "Authorization: ******"
 
# Saudi weekend is Friday–Saturday; the API respects local weekend rules automatically.
 
# Get a list of public holidays in a year
curl "https://khaleejiapi.dev/api/v1/calendar/holidays?country=AE&year=2025" \
  -H "Authorization: ******"
  • Weekend rules applied per country: KSA uses Fri–Sat; UAE uses Sat–Sun (since January 2022); Qatar, Kuwait, Bahrain, and Oman use Fri–Sat. The API returns the correct next business day for each country code.
  • Hijri dates: All calendar responses include the Hijri equivalent via the hijriDate field.
  • Forward planning: use the holidays endpoint to pre-load the full year and cache locally to avoid per-request latency on business-day checks.

5. Arabic Text Processing & Bilingual Support

KhaleejiAPI accepts Arabic Unicode input across all endpoints (emails, phone numbers, addresses, names) and returns Arabic strings in responses. The AI Translation API supports Gulf Arabic, Modern Standard Arabic (MSA), Egyptian, and Levantine dialects.

bash
# Validate an Arabic email address (Unicode display name)
curl -X GET "https://khaleejiapi.dev/api/v1/email/validate?email=مستخدم@example.com" \
  -H "Authorization: ******"
 
# Translate text to Arabic (Gemini 2.5 Flash)
curl -X POST "https://khaleejiapi.dev/api/v1/translate" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to KhaleejiAPI — the Middle East developer platform.",
    "targetLanguage": "ar",
    "dialect": "gulf"
  }'
 
# Response excerpt:
# { "data": { "translation": "مرحباً بك في خليجي API — منصة المطورين في الشرق الأوسط." } }

TypeScript example with RTL detection:

typescript
import { KhaleejiAPI } from "@khaleejiapi/sdk";
 
const client = new KhaleejiAPI({ apiKey: process.env.KHALEEJI_API_KEY! });
 
// Translate to Gulf Arabic
const result = await client.translation.translate({
  text: "Invoice total",
  targetLanguage: "ar",
  dialect: "gulf",   // "gulf" | "msa" | "egyptian" | "levantine"
});
console.log(result.translation); // "إجمالي الفاتورة"
 
// Check if a string is RTL (useful for UI rendering decisions)
const isRTL = /[؀-ۿ]/.test(result.translation);
console.log("Render RTL:", isRTL); // true
  • RTL rendering: Arabic strings use Unicode code points U+0600–U+06FF. Test with the simple regex above or use the Intl.Locale API.
  • Phone numbers: The phone validation API recognises Gulf country codes (+971 UAE, +966 KSA, +974 Qatar, +965 Kuwait, +973 Bahrain, +968 Oman) and returns carrier, line type, and formatted number.
  • IBAN & Emirates ID: Full GCC IBAN validation (/api/v1/iban/validate) and Emirates ID structure check (/api/v1/emiratesid/validate) are production-ready.

Summary Checklist