# KhaleejiAPI — Full API Reference

> The MENA region's developer API platform. 26+ production REST APIs for validation, geolocation, finance, media, identity, Islamic finance, and utilities.

Base URL: `https://khaleejiapi.dev/api`
Authentication: `X-API-Key` header
Response Format: JSON (except binary endpoints)
Region: AWS me-central-1 (UAE)

---

## Authentication

Every request must include your API key:

```
X-API-Key: YOUR_API_KEY
```

Get a free key at https://khaleejiapi.dev/signup (1,000 requests/month).

SDK initialization:

```typescript
// TypeScript
import { KhaleejiAPI } from '@khaleejiapi/sdk';
const client = new KhaleejiAPI({ apiKey: 'YOUR_API_KEY' });
```

```python
# Python
from khaleejiapi import KhaleejiAPI
client = KhaleejiAPI(api_key="YOUR_API_KEY")
```

---

## Data Validation APIs

### POST /v1/email/validate

Validate an email address with syntax, domain, MX record, and disposable provider checks.

**Parameters:**
- `email` (string, required): Email address to validate

**Example:**
```
GET /api/v1/email/validate?email=user@khaleejiapi.dev
```

**Response:**
```json
{
  "valid": true,
  "email": "user@khaleejiapi.dev",
  "domain": "khaleejiapi.dev",
  "mx_valid": true,
  "disposable": false,
  "suggestion": null
}
```

### GET /v1/phone/validate

Validate international phone numbers with carrier and type detection.

**Parameters:**
- `phone` (string, required): Phone number (E.164 or national format)
- `country` (string, optional): ISO country code (e.g., "AE", "SA")

**Response:**
```json
{
  "valid": true,
  "phone": "+971501234567",
  "country": "AE",
  "carrier": "Etisalat",
  "type": "mobile",
  "international_format": "+971 50 123 4567"
}
```

### GET /v1/vat/validate

Validate UAE and GCC VAT/TRN numbers with check-digit verification.

**Parameters:**
- `trn` (string, required): Tax Registration Number

**Response:**
```json
{
  "valid": true,
  "trn": "100234567890003",
  "country": "AE",
  "company_name": "Example LLC"
}
```

### GET /v1/iban/validate

Validate IBANs with bank and branch information for MENA region.

**Parameters:**
- `iban` (string, required): IBAN to validate

**Response:**
```json
{
  "valid": true,
  "iban": "AE070331234567890123456",
  "country": "AE",
  "bank": "Abu Dhabi Commercial Bank",
  "bank_code": "033"
}
```

### POST /v1/validation/saudi-id

Validate Saudi National IDs and Iqama numbers using Luhn algorithm. Supports batch validation.

**Parameters (single):**
- `id` (string, required): Saudi ID or Iqama number (10 digits)

**Parameters (batch):**
- `ids` (string[], required): Array of IDs to validate (max 100)

**Response (single):**
```json
{
  "valid": true,
  "id": "1234567890",
  "type": "citizen",
  "checksum_valid": true
}
```

**SDK:**
```typescript
const result = await client.validation.validateSaudiId({ id: '1234567890' });
const batch = await client.validation.validateSaudiIdBatch({ ids: ['1234567890', '2098765432'] });
```

---

## Geolocation APIs

### GET /v1/ip/lookup

Get location, ISP, and threat data from an IP address.

**Parameters:**
- `ip` (string, optional): IP address (defaults to caller's IP)

**Response:**
```json
{
  "ip": "185.1.2.3",
  "country": "AE",
  "country_name": "United Arab Emirates",
  "city": "Dubai",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "isp": "Etisalat",
  "threat_level": "low"
}
```

### GET /v1/timezone

Get timezone data by location name with DST support.

**Parameters:**
- `location` (string, required): City or location name (e.g., "Dubai", "Riyadh")

**Response:**
```json
{
  "location": "Dubai",
  "timezone": "Asia/Dubai",
  "utc_offset": "+04:00",
  "dst_active": false,
  "current_time": "2026-02-22T13:00:00+04:00"
}
```

### GET /v1/geocode

Convert addresses to coordinates. 100+ MENA locations supported.

**Parameters:**
- `address` (string, required): Address or city to geocode

**Response:**
```json
{
  "address": "Burj Khalifa, Dubai",
  "latitude": 25.1972,
  "longitude": 55.2744,
  "country": "AE",
  "formatted_address": "Burj Khalifa, Downtown Dubai, Dubai, UAE"
}
```

---

## Finance APIs

### GET /v1/exchange/rates

Real-time currency exchange rates. Data from open.er-api.com, cached 1 hour.

**Parameters:**
- `base` (string, optional, default: "AED"): Base currency code
- `symbols` (string, optional): Comma-separated target currencies

**Response:**
```json
{
  "base": "AED",
  "date": "2026-02-22",
  "rates": {
    "USD": 0.2723,
    "EUR": 0.2512,
    "GBP": 0.2156,
    "SAR": 1.0208
  },
  "source": "open.er-api.com",
  "cached": true
}
```

**SDK:**
```typescript
const rates = await client.finance.getExchangeRates({ base: 'AED', symbols: ['USD', 'EUR'] });
```

### GET /v1/vat/calculate

Calculate VAT for GCC countries with automatic rate detection.

**Parameters:**
- `amount` (number, required): Amount before or after tax
- `country` (string, optional, default: "AE"): GCC country code
- `inclusive` (boolean, optional, default: false): Whether amount includes VAT

**Response:**
```json
{
  "amount": 100,
  "vat_rate": 5,
  "vat_amount": 5,
  "total": 105,
  "country": "AE"
}
```

### GET /v1/holidays

Public holidays for all 6 GCC countries (2025-2026).

**Parameters:**
- `country` (string, optional, default: "AE"): GCC country code
- `year` (number, optional): Year (2025 or 2026)

**Response:**
```json
{
  "country": "AE",
  "year": 2026,
  "holidays": [
    {
      "name": "New Year's Day",
      "date": "2026-01-01",
      "type": "national"
    }
  ]
}
```

### GET /v1/business-days

Calculate business days between dates for GCC. Supports count, add, and subtract modes.

**Parameters:**
- `from` (string, required): Start date (YYYY-MM-DD)
- `to` (string, required for count mode): End date
- `days` (number, required for add/subtract mode): Number of business days
- `country` (string, optional, default: "AE"): GCC country code
- `mode` (string, optional, default: "count"): "count", "add", or "subtract"

**Response (count mode):**
```json
{
  "from": "2026-02-01",
  "to": "2026-02-28",
  "business_days": 20,
  "total_days": 27,
  "weekends": 8,
  "holidays": 0,
  "country": "AE"
}
```

**SDK:**
```typescript
const result = await client.finance.getBusinessDays({ from_date: '2026-02-01', to_date: '2026-02-28', country: 'AE' });
```

---

## Media & Files APIs

### POST /v1/image/process

Process images with sharp. Returns binary image data.

**Parameters (multipart/form-data):**
- `image` (file, required): Image file (JPEG, PNG, WebP, etc.)
- `operation` (string, required): "resize", "crop", "blur", "sharpen", "grayscale", "rotate", "compress"
- `width` (number, optional): Target width
- `height` (number, optional): Target height
- `quality` (number, optional): Output quality (1-100)
- `format` (string, optional): Output format ("jpeg", "png", "webp")

**Response:** Binary image data with appropriate Content-Type header.

### POST /v1/pdf/generate

Generate PDF documents via pdf-lib. Returns binary PDF data.

**Parameters (JSON body):**
- `type` (string, required): "invoice", "receipt", "report"
- `data` (object, required): Document content (varies by type)

**Response:** Binary PDF data with `Content-Type: application/pdf`.

---

## Identity & Security APIs

### GET /v1/validation/emirates-id

Validate and parse UAE Emirates ID numbers using Luhn algorithm.

**Parameters:**
- `id` (string, required): 15-digit Emirates ID number

**Response:**
```json
{
  "valid": true,
  "id": "784-1990-1234567-8",
  "nationality_code": "784",
  "birth_year": 1990,
  "checksum_valid": true
}
```

### POST /v1/fraud/check

Detect fraudulent IPs, emails, and phone numbers with heuristic scoring.

**Parameters:**
- `ip` (string, optional): IP to check
- `email` (string, optional): Email to check
- `phone` (string, optional): Phone to check

**Response:**
```json
{
  "risk_score": 15,
  "risk_level": "low",
  "checks": {
    "ip_proxy": false,
    "email_disposable": false,
    "phone_voip": false
  }
}
```

---

## Utility APIs

### POST /v1/qr/generate

Generate QR codes with custom styling.

**Parameters:**
- `data` (string, required): Content to encode
- `size` (number, optional, default: 256): Image size in pixels
- `format` (string, optional, default: "png"): "png" or "svg"
- `foreground` (string, optional): Hex color for foreground
- `background` (string, optional): Hex color for background

**Response:** Binary image data (PNG or SVG).

### POST /v1/translate

AI-powered translation via Google Gemini 2.5 Flash. Supports 22+ languages with transliteration, formality control, and dialect selection.

**Parameters (JSON body):**
- `text` (string, required): Text to translate
- `source` (string, optional): Source language code (auto-detected if omitted)
- `target` (string, required): Target language code
- `formality` (string, optional): "formal", "informal", "neutral"
- `dialect` (string, optional): Regional dialect (e.g., "gulf", "egyptian", "levantine" for Arabic)

**Supported Languages:** ar, en, fa, fr, de, hi, id, it, ja, ko, ms, nl, pl, pt, ru, es, sw, th, tr, uk, ur, zh

**Response:**
```json
{
  "translated_text": "مرحبا بالعالم",
  "source_language": "en",
  "target_language": "ar",
  "confidence": 0.98,
  "transliteration": "marhaba bil'alam",
  "model": "gemini-2.5-flash",
  "cached": false
}
```

**SDK:**
```typescript
const result = await client.communication.translateAI({ text: 'Hello world', target: 'ar', formality: 'formal' });
```

### GET /v1/weather

Real-time weather and 7-day forecasts. Data from Open-Meteo API, cached 30 minutes.

**Parameters:**
- `city` (string, required): City name (e.g., "Dubai", "Riyadh", "Doha")

**Response:**
```json
{
  "city": "Dubai",
  "current": {
    "temperature": 28.5,
    "humidity": 65,
    "wind_speed": 15.2,
    "condition": "Clear",
    "uv_index": 8
  },
  "forecast": [
    {
      "date": "2026-02-22",
      "high": 32,
      "low": 21,
      "condition": "Sunny"
    }
  ]
}
```

### GET /v1/hijri/convert

Convert between Gregorian and Hijri (Islamic) calendars using Julian Day Number algorithm.

**Parameters:**
- `date` (string, required): Date in YYYY-MM-DD format
- `direction` (string, optional, default: "to_hijri"): "to_hijri" or "to_gregorian"

**Response:**
```json
{
  "gregorian": {
    "date": "2026-02-22",
    "day": 22,
    "month": 2,
    "year": 2026,
    "day_of_week": "Sunday"
  },
  "hijri": {
    "date": "1447-08-04",
    "day": 4,
    "month": 8,
    "month_name": "Sha'ban",
    "year": 1447,
    "day_of_week": "Al-Ahad"
  }
}
```

**SDK:**
```typescript
const hijri = await client.islamic.convertHijri({ date: '2026-02-22', direction: 'to_hijri' });
```

### GET /v1/prayer-times

Astronomical prayer time calculations. 5 calculation methods, 2 juristic schools, Qibla direction.

**Parameters:**
- `city` (string, required): City name or coordinates (lat,lng)
- `method` (string, optional, default: "mwl"): Calculation method ("mwl", "isna", "egypt", "makkah", "karachi")
- `school` (string, optional, default: "shafi"): Juristic school ("shafi" or "hanafi")
- `date` (string, optional): Date in YYYY-MM-DD format

**Response:**
```json
{
  "city": "Dubai",
  "date": "2026-02-22",
  "prayers": {
    "fajr": "05:42",
    "sunrise": "06:55",
    "dhuhr": "12:32",
    "asr": "15:48",
    "maghrib": "18:10",
    "isha": "19:24"
  },
  "qibla": {
    "direction": 254.7,
    "distance_km": 1234.5
  },
  "method": "mwl"
}
```

**SDK:**
```typescript
const times = await client.islamic.getPrayerTimes({ city: 'Dubai', method: 'mwl' });
```

### POST /v1/arabic/process

Arabic text processing with 7 operations.

**Parameters (JSON body):**
- `text` (string, required): Arabic text to process
- `operation` (string, required): One of: "remove_diacritics", "normalize", "transliterate", "detect_script", "convert_numbers", "word_count", "sentiment"

**Response (example for transliterate):**
```json
{
  "original": "مرحبا بالعالم",
  "result": "marhaba bil'alam",
  "operation": "transliterate"
}
```

**SDK:**
```typescript
const result = await client.islamic.processArabic({ text: 'مرحبا', operation: 'transliterate' });
```

### POST /v1/url/shorten

Shorten URLs with click analytics.

**Parameters:**
- `url` (string, required): URL to shorten
- `custom_alias` (string, optional): Custom short code

**Response:**
```json
{
  "short_url": "https://khaleejiapi.dev/s/abc123",
  "original_url": "https://example.com/very/long/url",
  "alias": "abc123",
  "clicks": 0
}
```

---

## Islamic Finance APIs

### GET /v1/zakat/calculate

Calculate Zakat (Islamic alms tax) with Nisab threshold validation. Simple or multi-asset mode with live gold/silver prices.

**Parameters (Simple mode):**
- `amount` (number, required): Total wealth amount
- `currency` (string, optional, default: "AED"): Currency code

**Parameters (Detailed mode — GET with assets query or POST body):**
- `assets` (JSON array): Array of assets, each with:
  - `type` (string, required): One of: "cash", "gold", "silver", "stocks", "business", "agriculture", "mutual_funds", "crypto", "real_estate"
  - `value` (number, required): Asset value
  - `currency` (string, optional): Asset currency
  - `weight` (number, optional): Weight for gold/silver
  - `unit` (string, optional): "gram", "ounce", or "tola"

**Response:**
```json
{
  "totalWealth": 50000,
  "currency": "AED",
  "nisab": {
    "gold": { "threshold_grams": 87.48, "value": 30635.04 },
    "silver": { "threshold_grams": 612.36, "value": 2367.68 },
    "applied": "silver",
    "threshold": 2367.68
  },
  "aboveNisab": true,
  "zakatRate": 0.025,
  "zakatDue": 1250,
  "zakatableWealth": 50000,
  "method": "simple"
}
```

**SDK:**
```typescript
const zakat = await client.finance.calculateZakat({ amount: 50000, currency: 'AED' });
```

### GET /v1/sukuk/list

Reference data for 12 GCC sovereign and corporate sukuk (Islamic bonds). Filter, search, and get summary statistics.

**Parameters:**
- `id` (string, optional): Look up specific sukuk by ID
- `country` (string, optional): Filter by country (AE, SA, QA, BH, OM, KW)
- `type` (string, optional): Filter by structure (Ijara, Murabaha, Wakala, Mudaraba, Hybrid)
- `status` (string, optional): Filter by status (Active, Matured)
- `sector` (string, optional): Filter by sector (Sovereign, Banking, Real Estate, Energy, Aviation, Green)
- `currency` (string, optional): Filter by currency
- `min_size` / `max_size` (number, optional): Filter by issuance size
- `types` (string, optional): Set to "true" for sukuk type descriptions

**Response:**
```json
{
  "sukuk": [
    {
      "id": "sukuk-uae-sovereign-2025",
      "name": "UAE Federal Sukuk",
      "issuer": "UAE Ministry of Finance",
      "country": "AE",
      "type": "Ijara",
      "currency": "USD",
      "size": 1500000000,
      "couponRate": 4.95,
      "issueDate": "2025-01-15",
      "maturityDate": "2030-01-15",
      "status": "Active",
      "sector": "Sovereign",
      "rating": "Aa2/AA"
    }
  ],
  "summary": {
    "total": 12,
    "totalSize": 28850000000,
    "averageCoupon": 4.93
  }
}
```

**SDK:**
```typescript
const sukuk = await client.finance.listSukuk({ country: 'AE', type: 'Ijara' });
```

### GET /v1/takaful/calculate

Estimate Takaful (Islamic insurance) contributions for 6 insurance types across GCC countries. Supports Wakalah and Hybrid models.

**Parameters:**
- `type` (string, required): Insurance type — "health", "motor", "property", "life", "travel", "business"
- `coverage` (number, required): Coverage amount
- `country` (string, optional, default: "AE"): GCC country code
- `currency` (string, optional, default: "AED"): Currency code
- `model` (string, optional, default: "wakalah"): "wakalah" or "hybrid"
- `age` (integer, optional): Age of insured (for health/life)
- `vehicle_value` (number, optional): Vehicle value (for motor)
- `vehicle_year` (integer, optional): Vehicle year (for motor)
- `models` (string, optional): Set to "true" for available models, types, and countries info

**Response:**
```json
{
  "type": "health",
  "model": "wakalah",
  "coverage": 100000,
  "currency": "AED",
  "country": "AE",
  "annualContribution": 3225,
  "monthlyContribution": 268.75,
  "breakdown": {
    "basePremium": 3000,
    "countryFactor": 1.0,
    "adjustments": { "ageLoading": 0.075 },
    "wakalahFee": 806.25,
    "riskPoolContribution": 2418.75,
    "estimatedSurplus": 241.88
  }
}
```

**SDK:**
```typescript
const takaful = await client.finance.calculateTakaful({ type: 'health', coverage: 100000 });
```

---

## Rate Limits

Responses include rate limit headers:
- `X-RateLimit-Limit`: Requests per window
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Window reset time (Unix timestamp)

## Error Responses

All errors follow this format:
```json
{
  "error": "Error message description",
  "status": 400
}
```

Common status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden/scope), 429 (rate limited), 500 (server error).

## Scopes

API keys can be scoped to specific API groups:
- `validation:*` — All validation APIs
- `geo:*` — IP lookup, timezone, geocoding
- `finance:*` — Exchange rates, VAT, holidays, business days
- `finance:zakat` — Zakat calculator
- `finance:sukuk` — Sukuk tracker
- `finance:takaful` — Takaful calculator
- `media:*` — Image processing, PDF generation
- `communication:*` — Translation
- `utilities:*` — QR codes, URL shortener, weather
- `utilities:hijri` — Hijri calendar
- `utilities:prayer-times` — Prayer times
- `utilities:arabic` — Arabic text processing
- `*` — All APIs

## Links

- Website: https://khaleejiapi.dev
- Documentation: https://khaleejiapi.dev/docs
- OpenAPI Spec: https://khaleejiapi.dev/openapi.json
- TypeScript SDK: https://www.npmjs.com/package/@khaleejiapi/sdk
- Python SDK: https://pypi.org/project/khaleejiapi/
- Go SDK: https://github.com/khaleejiapi/sdk-go
- Swift SDK: https://github.com/xidioda/khaleejiapi (sdk/swift)
- Kotlin SDK: https://github.com/xidioda/khaleejiapi (sdk/kotlin)
- PHP SDK: https://github.com/xidioda/khaleejiapi (sdk/php)
- MCP Server: https://www.npmjs.com/package/@khaleejiapi/mcp-server
- LangChain SDK: https://pypi.org/project/khaleejiapi-langchain/
- OpenAI Plugin Manifest: https://khaleejiapi.dev/.well-known/ai-plugin.json
- Agent Discovery (A2A): https://khaleejiapi.dev/.well-known/agent.json
- Status: https://khaleejiapi.dev/status
- GitHub: https://github.com/xidioda/khaleejiapi