Overview

langchain-saudi-gov is a production-ready LangChain partner package that wraps 27 Saudi Arabian government and public service APIs into LangChain-compatible tools. It enables AI agents to query national addresses, verify commercial registrations, search open data portals, check prayer times, and much more — all with native Arabic/English bilingual support.

Why this toolkit?

• 🏛️ 27 tools across 7 government domains — the most comprehensive Saudi API toolkit available
• 🔑 16 tools work with zero configuration — no API keys required for open data portals
• 🌐 Bilingual Arabic/English — auto-detects query language, returns bilingual results
• 🤖 LangChain-native — every tool is a BaseTool subclass, ready for agents and chains
• ⚡ Async-first — all tools support both sync and async execution
• 🧪 Fully tested — 116 unit tests with mocked HTTP, zero network dependency

📦 Installation

pip install langchain-saudi-gov

Or with development dependencies:

pip install "langchain-saudi-gov[dev]"

🚀 Quick Start

Zero-config — no API keys needed

from langchain_saudi_gov import SaudiGovToolkit

# 16 tools work out of the box with no API keys
toolkit = SaudiGovToolkit()
tools = toolkit.get_tools()
print(f"{len(tools)} tools ready!")  # 16 tools ready!

Use with a LangChain agent

from langchain_saudi_gov import SaudiGovToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

toolkit = SaudiGovToolkit(
    national_address_key="your-key",   # Free from api.address.gov.sa
    wathq_key="your-wathq-key",        # From developer.wathq.sa
    najiz_key="your-najiz-key",        # From developers.najiz.sa
)

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=toolkit.get_tools(),  # All 27 tools
)

# Ask in Arabic
result = agent.invoke({
    "messages": [{"role": "user", "content": "ابحث عن عنوان مطار الملك عبدالعزيز في جدة"}]
})

# Ask in English
result = agent.invoke({
    "messages": [{"role": "user", "content": "Look up commercial registration 1010123456"}]
})

Use individual tools directly

from langchain_saudi_gov.tools.cultural import PrayerTimesTool, HijriDateTool
from langchain_saudi_gov.tools.statistics import KAPSARCEnergyTool

# Prayer times — no API key
prayer = PrayerTimesTool()
print(prayer.invoke({"city": "Riyadh"}))
# Prayer times for Riyadh — 15 Jul 2025 (18 Muharram 1447)
#   Fajr:    03:35
#   Dhuhr:   12:10
#   Asr:     15:33
#   Maghrib: 18:54
#   Isha:    20:24

# Hijri conversion
hijri = HijriDateTool()
print(hijri.invoke({"date": "01-01-2025", "to_hijri": True}))

# Energy data
energy = KAPSARCEnergyTool()
print(energy.invoke({"query": "Saudi oil production 2024"}))

Domain filtering

# Only load finance and statistics tools
toolkit = SaudiGovToolkit(domains=["finance", "statistics"])
tools = toolkit.get_tools()  # 7 tools from those domains only

# Disable cultural tools
toolkit = SaudiGovToolkit(include_cultural=False)

🛠️ Complete Tool Reference

📍 Location Domain (3 tools)

from langchain_saudi_gov.tools.location import (
    NationalAddressSearchTool,
    NationalAddressReverseGeocodeTool,
    BaladyMunicipalTool,
)

# Search by text (Arabic auto-detected)
address = NationalAddressSearchTool(api_key="your-key")
result = address.invoke({"query": "مطار الملك عبدالعزيز جدة"})
# Returns: building number, street, district, city, postcode, GPS

# Reverse geocode
reverse = NationalAddressReverseGeocodeTool(api_key="your-key")
result = reverse.invoke({"lat": 24.7136, "lng": 46.6753})

# Municipal data
balady = BaladyMunicipalTool()
result = balady.invoke({"query": "building permits Riyadh"})

🏢 Business Domain — Wathq (8 tools)

All 8 tools require a Wathq API key from developer.wathq.sa. They share the WathqBaseTool base class with unified auth, error handling, and rate-limit management.

from langchain_saudi_gov.tools.business import (
    CommercialRegistrationTool,
    TrademarkLookupTool,
    EmployeeInfoTool,
)

# Look up any Saudi company by CR number
cr = CommercialRegistrationTool(api_key="your-wathq-key")
result = cr.invoke({"cr_number": "1010123456"})
# Returns: Trade name, Status, Capital (SAR), Issue/Expiry dates, City, Activities

# Search trademarks
tm = TrademarkLookupTool(api_key="your-wathq-key")
result = tm.invoke({"query": "شركة الراجحي", "search_type": "name"})

# Check employee info
emp = EmployeeInfoTool(api_key="your-wathq-key")
result = emp.invoke({"cr_number": "1010123456"})

⚖️ Legal Domain (2 tools)

from langchain_saudi_gov.tools.legal import NajizVerificationTool, MoJOpenDataTool

# Verify a real estate deed
najiz = NajizVerificationTool(api_key="your-najiz-key")
result = najiz.invoke({
    "document_number": "310100012345",
    "document_type": "deed",
})

# Verify a power of attorney
result = najiz.invoke({
    "document_number": "440100067890",
    "document_type": "power_of_attorney",
    "identity_number": "1012345678",
})

# Search judicial open data
moj = MoJOpenDataTool()
result = moj.invoke({"query": "court statistics 2024"})

💰 Finance Domain (3 tools)

from langchain_saudi_gov.tools.finance import (
    ZATCAOpenDataTool,
    CMAFinancialDataTool,
    EtimadProcurementTool,
)

# Search ZATCA tax data
zatca = ZATCAOpenDataTool()
result = zatca.invoke({"query": "VAT collections 2024"})

# Capital markets data
cma = CMAFinancialDataTool()
result = cma.invoke({"query": "Tadawul listed companies"})

# Government procurement
etimad = EtimadProcurementTool()
result = etimad.invoke({"query": "IT infrastructure tenders"})

📊 Statistics Domain (4 tools)

from langchain_saudi_gov.tools.statistics import (
    GASTATTool,
    KAPSARCEnergyTool,
    SaudiOpenDataSearchTool,
    HRSDLabourTool,
)

# Population and economic statistics
gastat = GASTATTool()
result = gastat.invoke({"query": "population census 2024"})

# Energy and oil data
kapsarc = KAPSARCEnergyTool()
result = kapsarc.invoke({"query": "Saudi oil production OPEC"})

# Search all government datasets
opendata = SaudiOpenDataSearchTool()
result = opendata.invoke({"query": "education enrollment", "organization": "ministry-of-education"})

# Labour market
hrsd = HRSDLabourTool()
result = hrsd.invoke({"query": "Saudization employment rates"})

🏭 Sector Domain (5 tools)

from langchain_saudi_gov.tools.sector import (
    HealthDataTool,
    TelecomDataTool,
    AgricultureDataTool,
    IndustrialDataTool,
    MonshaatSMETool,
)

# Healthcare data
health = HealthDataTool()
result = health.invoke({"query": "hospital bed capacity"})

# Telecommunications
telecom = TelecomDataTool()
result = telecom.invoke({"query": "5G coverage statistics"})

# Agriculture
agri = AgricultureDataTool()
result = agri.invoke({"query": "water consumption agriculture"})

# Industrial data
industrial = IndustrialDataTool()
result = industrial.invoke({"query": "manufacturing output"})

# SME ecosystem
monshaat = MonshaatSMETool()
result = monshaat.invoke({"query": "startup funding statistics"})

🕌 Cultural Domain (2 tools)

from langchain_saudi_gov.tools.cultural import PrayerTimesTool, HijriDateTool

# Prayer times for any Saudi city
prayer = PrayerTimesTool()
result = prayer.invoke({"city": "Makkah"})
# Prayer times for Makkah — 15 Jul 2025 (18 Muharram 1447)
#   Fajr:    04:28    Dhuhr:   12:27
#   Asr:     15:48    Maghrib: 19:15
#   Isha:    20:45

# With specific date
result = prayer.invoke({"city": "Medina", "date": "01-01-2025"})

# Gregorian → Hijri
hijri = HijriDateTool()
result = hijri.invoke({"date": "25-12-2024", "to_hijri": True})

# Hijri → Gregorian
result = hijri.invoke({"date": "01-07-1446", "to_hijri": False})

🏗️ Architecture

langchain-saudi-gov/
├── langchain_saudi_gov/
│   ├── __init__.py              # Exports all 27 tools + SaudiGovToolkit
│   ├── toolkit.py               # Unified toolkit with domain filtering
│   ├── tools/
│   │   ├── _base.py             # WathqBaseTool & CKANBaseTool base classes
│   │   ├── location/            # Address search, reverse geocode, Balady
│   │   ├── business/            # 8 Wathq tools (CR, contracts, deeds, etc.)
│   │   ├── legal/               # Najiz verification, MoJ open data
│   │   ├── finance/             # ZATCA, CMA, Etimad
│   │   ├── statistics/          # GASTAT, KAPSARC, Open Data, HRSD
│   │   ├── sector/              # Health, Telecom, Agriculture, Industrial, SME
│   │   └── cultural/            # Prayer times, Hijri dates
│   └── utils/
│       └── arabic.py            # Arabic text normalization, language detection
├── tests/
│   ├── unit_tests/              # 116 tests, fully mocked (respx)
│   └── integration_tests/       # Live API tests
├── docs/                        # Detailed documentation
├── pyproject.toml               # Package config
├── Makefile                     # dev commands
└── LICENSE                      # MIT

Base Classes

The toolkit uses two shared base classes to reduce boilerplate:

• WathqBaseTool — Shared by all 8 Wathq/Ministry of Commerce tools. Provides unified authentication (apiKey header), HTTP client management, and error handling (401, 404, 429 rate-limit).

• CKANBaseTool — Shared by 10+ open data tools (ZATCA, CMA, GASTAT, Health, etc.). Provides _ckan_search() with CKAN package_search API, organization filtering via fq parameter, and standardized result formatting.

# How WathqBaseTool simplifies tool creation:
class CommercialRegistrationTool(WathqBaseTool):
    name = "saudi_commercial_registration"
    # ... just define _run() and _format()

    def _run(self, cr_number: str) -> str:
        data = self._wathq_get(f"/v5/commercialregistration/info/{cr_number}")
        return self._format(data)

🔑 API Keys Reference

Environment variables (recommended)

export NATIONAL_ADDRESS_API_KEY="your-key-here"
export WATHQ_API_KEY="your-wathq-key"
export NAJIZ_API_KEY="your-najiz-key"

import os
from langchain_saudi_gov import SaudiGovToolkit

toolkit = SaudiGovToolkit(
    national_address_key=os.getenv("NATIONAL_ADDRESS_API_KEY"),
    wathq_key=os.getenv("WATHQ_API_KEY"),
    najiz_key=os.getenv("NAJIZ_API_KEY"),
)

🌍 Real-World Use Cases

1. 🏢 Business Due Diligence Agent

"""AI agent that performs company due diligence on Saudi companies."""

from langchain_saudi_gov import SaudiGovToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

toolkit = SaudiGovToolkit(
    wathq_key="your-key",
    domains=["business"],
)

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=toolkit.get_tools(),
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "Perform due diligence on CR 1010123456. "
            "Check the registration status, financial statements, "
            "employee count, and verify their chamber membership."
        ),
    }]
})

2. 📊 Saudi Economic Research Assistant

"""Research assistant for Saudi economic data and Vision 2030 metrics."""

toolkit = SaudiGovToolkit(domains=["statistics", "finance"])
agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=toolkit.get_tools(),
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "I need data on Saudi Arabia's economic diversification. "
            "Find non-oil GDP statistics, labour market Saudization rates, "
            "and recent energy production data from KAPSARC."
        ),
    }]
})

3. 🏠 Real Estate Verification Bot

"""Verify real estate transactions with address and deed data."""

toolkit = SaudiGovToolkit(
    national_address_key="your-key",
    najiz_key="your-najiz-key",
    domains=["location", "legal"],
)

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=toolkit.get_tools(),
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "Verify the title deed 310100012345 and find the "
            "national address at coordinates 24.7136, 46.6753"
        ),
    }]
})

4. 🕌 Saudi Lifestyle Assistant

"""Culturally-aware assistant for daily Saudi life."""

toolkit = SaudiGovToolkit(
    domains=["cultural", "location"],
    national_address_key="your-key",
)

agent = create_react_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=toolkit.get_tools(),
)

# Works in Arabic
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "ما مواقيت الصلاة اليوم في الرياض؟ وما التاريخ الهجري؟",
    }]
})

📋 Arabic Language Support

All tools support bilingual Arabic and English input and output:

from langchain_saudi_gov.utils.arabic import (
    normalize_arabic,
    remove_diacritics,
    detect_language,
    is_arabic,
)

normalize_arabic("الرِّيَاض")        # → "الرياض"
remove_diacritics("بِسْمِ اللَّهِ")   # → "بسم الله"
detect_language("مطار الملك خالد")   # → "A" (Arabic)
detect_language("King Khalid Airport") # → "E" (English)
is_arabic("الرياض")                  # → True

🧪 Development

Setup

git clone https://github.com/fouadmahmoud283-ai/langchain-saudi-gov.git
cd langchain-saudi-gov
pip install -e ".[dev]"

Commands

make test              # Run 116 unit tests (mocked, no network)
make integration_tests # Run live API tests (needs keys + network)
make lint              # Lint with ruff
make format            # Auto-format with ruff

Running tests

# All unit tests
pytest tests/unit_tests -v

# Specific domain
pytest tests/unit_tests/test_business.py -v
pytest tests/unit_tests/test_cultural.py -v

# With coverage
pytest tests/unit_tests --cov=langchain_saudi_gov

Project structure

tests/
├── unit_tests/
│   ├── test_arabic.py       # 24 tests — Arabic text normalization
│   ├── test_base.py         # 7 tests — WathqBaseTool & CKANBaseTool
│   ├── test_business.py     # 5 tests — CR, contracts, trademark, chamber
│   ├── test_cultural.py     # 6 tests — prayer times, Hijri conversion
│   ├── test_data_tools.py   # 10 tests — ZATCA, CMA, Etimad, GASTAT, KAPSARC
│   ├── test_imports.py      # 30 tests — all 28 exports importable
│   ├── test_legal.py        # 6 tests — Najiz verification, MoJ data
│   ├── test_location.py     # 8 tests — address search, reverse geocode, Balady
│   ├── test_sector.py       # 8 tests — health, telecom, agriculture, SME
│   └── test_toolkit.py      # 12 tests — toolkit config, domains, toggles
└── integration_tests/       # Live API tests (optional)

🔧 Configuration Reference

SaudiGovToolkit parameters

Available domains

📄 API Coverage

🤝 Contributing

We welcome contributions! Whether it's adding new Saudi API integrations, improving documentation, or fixing bugs:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-tool)
3. Write tests for your changes
4. Run make lint && make test to verify
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

📄 License

MIT — see LICENSE for details.

🙏 Acknowledgments

• LangChain for the tool framework
• Saudi government digital transformation teams for providing public APIs
• Aladhan for the Islamic prayer times API
• KAPSARC for the energy data API