# KhaleejiAPI

> The MENA region's developer API platform. 26+ production APIs for validation, geolocation, finance, media, identity, Islamic finance, and utilities — purpose-built for Middle East applications.

## Overview

KhaleejiAPI provides REST APIs for Middle East and North Africa (MENA) developers. All APIs return JSON, use API key authentication via `X-API-Key` header, and are hosted on AWS me-central-1 (UAE). Base URL: `https://khaleejiapi.dev/api`

## SDKs

- TypeScript/JavaScript: `npm install @khaleejiapi/sdk` (v1.2.0)
- Python: `pip install khaleejiapi` (v1.2.0)
- Go: `go get github.com/khaleejiapi/sdk-go` (v1.1.0)
- Swift (iOS): KhaleejiAPI via SPM (v1.1.0)
- Kotlin (Android): `dev.khaleejiapi:khaleejiapi-sdk:1.1.0` (Gradle/Maven)
- PHP: `composer require khaleejiapi/sdk` (v1.1.0)

## AI Agent Integration

- MCP Server: `npx @khaleejiapi/mcp-server` (v1.1.0) — 25 tools for Claude, Copilot, Cursor, etc.
- LangChain/CrewAI: `pip install khaleejiapi-langchain` (v1.1.0) — 24 StructuredTool definitions
- OpenAI Plugin: `https://khaleejiapi.dev/.well-known/ai-plugin.json`
- Agent Discovery (A2A): `https://khaleejiapi.dev/.well-known/agent.json`
- OpenAPI Spec: `https://khaleejiapi.dev/openapi.json`

## API Categories

### Data Validation
- [Email Validation](/docs/v1/email/validate): Verify emails with syntax, domain, MX, and disposable checks
- [Phone Validation](/docs/v1/phone/validate): Validate international phone numbers with carrier detection
- [VAT Validation](/docs/v1/vat/validate): Validate UAE and GCC VAT/TRN numbers
- [IBAN Validation](/docs/v1/iban/validate): Validate IBANs with bank info for MENA region
- [Saudi ID Validation](/docs/v1/validation/saudi-id): Validate Saudi National IDs and Iqama via Luhn algorithm (batch support)

### Geolocation
- [IP Geolocation](/docs/v1/ip/lookup): Location, ISP, and threat data from any IP
- [Timezone](/docs/v1/timezone): Timezone data by location with DST support
- [Geocoding](/docs/v1/geocode): Address-to-coordinates for 100+ MENA locations

### Finance
- [Exchange Rates](/docs/v1/exchange/rates): Real-time rates for 50+ currencies (source: open.er-api.com, 1h cache)
- [VAT Calculator](/docs/v1/vat/calculate): Calculate VAT with GCC rate detection
- [Public Holidays](/docs/v1/holidays): All 6 GCC countries, 2025-2026, Islamic calendar
- [Business Days Calculator](/docs/v1/business-days): Business days between dates for GCC (weekends + holidays)

### Islamic Finance
- [Zakat Calculator](/docs/v1/zakat/calculate): Multi-asset Zakat calculation with live gold/silver Nisab thresholds
- [Sukuk Tracker](/docs/v1/sukuk/list): 12 GCC sukuk reference data with filtering and summary statistics
- [Takaful Calculator](/docs/v1/takaful/calculate): Islamic insurance estimates for 6 types across GCC countries

### Media & Files
- [Image Processing](/docs/v1/image/process): Resize, crop, blur, sharpen via sharp (binary response)
- [PDF Generation](/docs/v1/pdf/generate): Generate invoices, receipts, reports via pdf-lib (binary response)

### Identity & Security
- [Emirates ID Validation](/docs/v1/validation/emirates-id): Validate and parse UAE Emirates ID numbers
- [Fraud Detection](/docs/v1/fraud/check): Detect suspicious IPs, emails, and phones

### Utilities
- [QR Code Generator](/docs/v1/qr/generate): QR codes with custom colors and formats
- [AI Translation](/docs/v1/translate): 22+ languages via Google Gemini 2.5 Flash (24h cache)
- [Weather](/docs/v1/weather): Real-time weather and 7-day forecasts via Open-Meteo (30min cache)
- [Hijri Calendar](/docs/v1/hijri/convert): Gregorian↔Hijri conversion via JDN algorithm
- [Prayer Times](/docs/v1/prayer-times): Astronomical calculations, 5 methods, Qibla direction
- [Arabic Text Processing](/docs/v1/arabic/process): Diacritics removal, transliteration, sentiment, 7 operations
- [URL Shortener](/docs/v1/url/shorten): URL shortening with click analytics

## Authentication

All API requests require an API key passed via the `X-API-Key` header:

```
curl -H "X-API-Key: YOUR_API_KEY" https://khaleejiapi.dev/api/v1/email/validate?email=user@example.com
```

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

## Pricing

| Plan | Monthly (AED) | Requests/month | Rate Limit |
|------|--------------|----------------|------------|
| Free | 0 | 1,000 | Standard |
| Starter | 69 | 100,000 | 300/min |
| Professional | 199 | 500,000 | 1,000/min |
| Business | 599 | Unlimited | Custom |

## Links

- Documentation: https://khaleejiapi.dev/docs
- API Reference: https://khaleejiapi.dev/docs/quickstart
- OpenAPI Spec: https://khaleejiapi.dev/openapi.json
- Status: https://khaleejiapi.dev/status
- Pricing: https://khaleejiapi.dev/pricing
- 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