Forem: xidioda xidioda

Islamic Finance APIs for Developers: Hijri Calendar, Prayer Times & More

xidioda xidioda — Wed, 25 Feb 2026 07:30:35 +0000

Building Islamic-Aware Applications

If you're building apps for Muslim users — whether that's a banking app, a productivity tool, or an e-commerce platform — you need Islamic calendar and prayer time support. Here's how KhaleejiAPI makes it easy.

Hijri Calendar Conversion

The Hijri (Islamic) calendar is used across the Muslim world for religious observances, government documents, and financial contracts. Converting between Gregorian and Hijri dates is surprisingly complex — the Islamic calendar is lunar-based with months of 29 or 30 days.

Quick Start

# Convert today to Hijri
curl "https://khaleejiapi.dev/api/v1/hijri/convert?today=true" \
  -H "X-API-Key: YOUR_KEY"

# Convert specific date
curl "https://khaleejiapi.dev/api/v1/hijri/convert?date=2026-03-01" \
  -H "X-API-Key: YOUR_KEY"

# Convert Hijri to Gregorian
curl "https://khaleejiapi.dev/api/v1/hijri/convert?hijri=1447-09-01" \
  -H "X-API-Key: YOUR_KEY"

Response

{
  "gregorian": {
    "date": "2026-02-22",
    "year": 2026,
    "month": 2,
    "day": 22,
    "monthName": "February",
    "dayOfWeek": "Sunday",
    "dayOfWeekAr": "الأحد"
  },
  "hijri": {
    "date": "1447-08-04",
    "year": 1447,
    "month": 8,
    "day": 4,
    "monthName": "Sha'ban",
    "monthNameAr": "شعبان"
  },
  "direction": "gregorian_to_hijri"
}

SDK Usage

const hijri = await client.islamic.convertHijri({
  date: '2026-03-01',
  direction: 'to_hijri'
});

// Check if it's Ramadan
if (hijri.hijri.month === 9) {
  console.log("It's Ramadan! 🌙");
}

Prayer Times

Our prayer times API uses astronomical calculations — not a database lookup. This means accurate times for any location on Earth, not just predefined cities.

5 Calculation Methods

Method	Used By
MWL (Muslim World League)	Most of the world
ISNA	North America
Egypt	Africa, Middle East
Makkah (Umm al-Qura)	Saudi Arabia
Karachi	Pakistan, South Asia

2 Juristic Schools

Shafi — Asr when shadow equals object length (most madhabs)
Hanafi — Asr when shadow equals twice object length

Quick Start

# By city name
curl "https://khaleejiapi.dev/api/v1/prayer-times?city=dubai" \
  -H "X-API-Key: YOUR_KEY"

# By coordinates with Hanafi school
curl "https://khaleejiapi.dev/api/v1/prayer-times?lat=21.4225&lng=39.8262&school=hanafi" \
  -H "X-API-Key: YOUR_KEY"

Response includes Qibla direction

{
  "prayers": {
    "fajr": "05:23",
    "sunrise": "06:42",
    "dhuhr": "12:30",
    "asr": "15:47",
    "maghrib": "18:15",
    "isha": "19:33"
  },
  "qibla": {
    "direction": 255.42,
    "compass": "WSW"
  }
}

Arabic Text Processing

Our Arabic NLP API supports 7 operations:

1. Remove Diacritics

Strip tashkeel from Arabic text:

curl -X POST "https://khaleejiapi.dev/api/v1/arabic/process" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "مَرْحَبًا بِالْعَالَمِ", "operation": "remove_diacritics"}'
# Result: "مرحبا بالعالم"

2. Transliterate

Convert Arabic to Latin script:

curl -X POST "https://khaleejiapi.dev/api/v1/arabic/process" \
  -d '{"text": "مرحبا بالعالم", "operation": "transliterate"}'
# Result: "mrhba bal'aalm"

3. Sentiment Analysis

Basic sentiment detection for Arabic text:

curl -X POST "https://khaleejiapi.dev/api/v1/arabic/process" \
  -d '{"text": "هذا المنتج ممتاز وجميل", "operation": "sentiment"}'
# Result: { "score": 0.8, "label": "positive" }

Use Cases

Banking apps — Show Hijri dates on statements, calculate Islamic finance terms
Prayer apps — Accurate times + Qibla for any location
E-commerce — Translate product descriptions, detect Arabic text
HR systems — Business day calculations for GCC countries
Government — Saudi ID validation, Emirates ID validation

Get Started

All Islamic APIs are included in the free tier (1,000 requests/month):

npm install @khaleejiapi/sdk
# or
pip install khaleejiapi

Originally published on KhaleejiAPI Blog. Sign up for a free API key at khaleejiapi.dev/signup — 1,000 requests/month, no credit card required.

How We Built an AI Translation API with Google Gemini

xidioda xidioda — Wed, 25 Feb 2026 07:15:16 +0000

Why AI Translation?

Traditional translation APIs (Google Translate, DeepL) work well for general text, but they struggle with:

Arabic dialects — Gulf Arabic vs Egyptian vs Levantine
Formality levels — Formal business Arabic vs casual chat
Context-aware translation — Technical terms, cultural nuances

We decided to use Google Gemini 2.5 Flash as our translation engine. It's fast (< 500ms), understands context, and supports dialect control.

Architecture

Client → /api/v1/translate → Cache Check (Valkey)
                                  ↓ miss
                             Gemini 2.5 Flash
                                  ↓
                             Cache Store (24h TTL)
                                  ↓
                             Response

The Prompt

The key to good AI translation is the prompt. Here's our approach:

Translate the following text from {source} to {target}.
Formality: {formality}
Dialect: {dialect}

Rules:
- Maintain the original meaning and tone
- Use the specified dialect if provided
- Return ONLY the translated text, no explanations

Caching Strategy

Translation is expensive (API credits + latency). We cache aggressively:

Cache key: Hash of text + source + target + formality + dialect
TTL: 24 hours in Valkey
Fallback: In-memory Map if Valkey is unavailable

This gives us 0ms latency on cache hits and reduces our Gemini API costs by ~80%.

SDK Usage

TypeScript

import { KhaleejiAPI } from '@khaleejiapi/sdk';

const client = new KhaleejiAPI({ apiKey: 'YOUR_KEY' });

const result = await client.communication.translateAI({
  text: 'Hello, how are you?',
  target: 'ar',
  formality: 'formal',
  dialect: 'gulf'
});

console.log(result.translated);
// "السلام عليكم، كيف حالكم؟"

Python

from khaleejiapi import KhaleejiAPI

client = KhaleejiAPI(api_key="YOUR_KEY")

result = client.translate(
    text="Hello, how are you?",
    target="ar",
    formality="formal",
    dialect="gulf"
)

print(result["translated"])
# "السلام عليكم، كيف حالكم؟"

Supported Languages

We support 22+ languages, including all major MENA languages:

Code	Language	Dialect Support
ar	Arabic	gulf, egyptian, levantine, maghrebi
fa	Persian	—
ur	Urdu	—
tr	Turkish	—
en	English	—
fr	French	—
hi	Hindi	—

Performance

Metric	Value
Cache hit latency	<5ms
Cache miss latency	300-500ms
Cache hit rate	~75%
Supported languages	22+
Max text length	5,000 chars

Try It

curl -X POST https://khaleejiapi.dev/api/v1/translate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Good morning", "target": "ar", "dialect": "gulf"}'

Get your free API key at khaleejiapi.dev/signup.

Originally published on KhaleejiAPI Blog. Sign up for a free API key at khaleejiapi.dev/signup — 1,000 requests/month, no credit card required.

Building the MENA Region's First Developer API Platform

xidioda xidioda — Wed, 25 Feb 2026 07:15:15 +0000

The Problem

Developers building applications for the Middle East face a fragmented landscape. Need Emirates ID validation? Build it yourself. Need Hijri calendar conversion? Find an unmaintained npm package. Need Saudi business day calculations? Write custom logic accounting for Friday-Saturday weekends and Islamic holidays.

Every MENA developer has reinvented these wheels. We decided to build them once, properly, and make them available as simple API calls.

Why KhaleejiAPI Exists

KhaleejiAPI is the first API platform purpose-built for the GCC and MENA region. We offer 26 production-ready APIs covering:

Validation — Emirates ID, Saudi ID (Iqama), IBAN, VAT/TRN, email, phone
Finance — Real-time exchange rates, VAT calculation, GCC public holidays, business day calculations
Islamic — Hijri calendar conversion, prayer times with Qibla direction, Arabic text processing (NLP)
Geolocation — IP lookup, timezone (DST-aware), geocoding for 100+ MENA locations
Media — Image processing (sharp), PDF generation (pdf-lib)
Communication — AI-powered translation via Google Gemini (22+ languages)

Every API uses real data sources — not mock data, not hardcoded responses.

Technical Decisions

Why Next.js?

We chose Next.js 16 as a monolith — API routes and frontend in one codebase. This lets us:

Ship faster — one deploy updates everything
Share types — TypeScript types flow from API to SDK to docs
Edge-ready — API routes can run on the edge when needed

Why AWS me-central-1?

Our compute runs in the UAE region (me-central-1). This gives our GCC users <50ms latency compared to 200ms+ from us-east-1. Data residency matters for compliance with UAE's PDPL and Saudi's PDPL.

Real Data, Not Mock Data

Every API returns real data:

Exchange rates from open.er-api.com (1-hour cache)
Weather from Open-Meteo (30-minute cache)
Translation via Google Gemini 2.5 Flash AI (24-hour cache)
Image processing with sharp (real binary output)
PDF generation with pdf-lib (real binary output)

Caching Strategy

We use Valkey (Redis-compatible) with in-memory fallback:

Exchange Rates → Valkey (1h TTL) → In-memory Map fallback
Translation    → Valkey (24h TTL) → In-memory Map fallback
Weather        → Valkey (30m TTL) → In-memory Map fallback

If Valkey is unavailable, the API still works — just without cross-instance cache sharing.

What's Next

We're shipping fast. Here's what's coming:

MCP Server — AI agents (Claude, Copilot, Cursor) can call our APIs directly
Mobile SDKs — Swift (iOS) and Kotlin (Android)
Blog — You're reading the first post!
Open Finance APIs — Aligned with UAE CBUAE Open Finance Regulation
Islamic Fintech — Zakat calculator, Sukuk tracking

Get Started

curl https://khaleejiapi.dev/api/v1/hijri/convert?today=true \
  -H "X-API-Key: YOUR_KEY"

We're building the infrastructure that MENA developers deserve. Join us.

Originally published on KhaleejiAPI Blog. Sign up for a free API key at khaleejiapi.dev/signup — 1,000 requests/month, no credit card required.