Getting Started

Welcome to the SAHMK API. Access real-time and historical Saudi stock market data for all 350+ companies listed on TASI and Nomu.

Quick Start

Create a free account
Get your API key from the dashboard
Make your first API request

Base URL

text

https://app.sahmk.sa/api/v1

Your First Request

curl -X GET "https://app.sahmk.sa/api/v1/quote/2222/" \
     -H "X-API-Key: YOUR_API_KEY"

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header.

http

X-API-Key: YOUR_API_KEY

API Key Types:
• shmk_live_* — Production keys
• shmk_test_* — Test keys (same data, separate quota)

curl -X GET "https://app.sahmk.sa/api/v1/quote/2222/" \
     -H "X-API-Key: YOUR_API_KEY"

Stocks

Get real-time stock quotes and prices for individual or multiple stocks.

GET /quote/{symbol}/

Free

Get current price and trading data for a single stock.

Path Parameters:

symbol — Stock ticker (e.g., 2222 for Aramco)

View Response

json

{
  "symbol": "2222",
  "name": "أرامكو السعودية",
  "name_en": "Saudi Arabian Oil Co",
  "price": 25.64,
  "change": 0.38,
  "change_percent": 1.5,
  "open": 25.3,
  "high": 25.68,
  "low": 25.3,
  "previous_close": 25.26,
  "volume": 15738067,
  "value": 402108076.72,
  "bid": 25.6,
  "ask": 25.64,
  "updated_at": "2026-01-28T12:19:48+00:00",
  "is_delayed": true
}

GET /quotes/

Free

Get quotes for multiple stocks in a single request.

Query Parameters:

symbols — Comma-separated tickers (max 50)

View Response

json

{
  "quotes": [
    {
      "symbol": "2222",
      "name": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 25.64,
      "change": 0.38,
      "change_percent": 1.5,
      "volume": 15738067,
      "updated_at": "2026-01-28T12:19:48+00:00",
      "is_delayed": true
    },
    {
      "symbol": "1120",
      "name": "الراجحي",
      "name_en": "Al Rajhi Banking & Investment Corp SJSC",
      "price": 108.6,
      "change": 0.2,
      "change_percent": 0.18,
      "volume": 4023570,
      "updated_at": "2026-01-28T12:18:56+00:00",
      "is_delayed": true
    }
  ],
  "count": 2
}

Market

Get market-wide data including index values, top movers, and sector performance.

GET /market/summary/

Free

Get TASI index value, volume, and market sentiment.

View Response

json

{
  "timestamp": "2026-01-28T12:20:00+00:00",
  "index_value": 11458.11,
  "index_change": 76.28,
  "index_change_percent": 0.67,
  "total_volume": 279874553,
  "advancing": 117,
  "declining": 139,
  "unchanged": 14,
  "market_mood": "bullish"
}

GET /market/gainers/

Free

Get top gaining stocks by percentage change.

Query Parameters:

limit — Number of results (default: 10, max: 50)

View Response

json

{
  "gainers": [
    {
      "symbol": "4194",
      "name": "مجموعة منزل التسويق للتجارة",
      "name_en": "Maison Marketing Trade Group",
      "price": 59.5,
      "change": 4.9,
      "change_percent": 8.97,
      "volume": 611349,
      "updated_at": "2026-01-28T12:19:50+00:00"
    }
  ],
  "count": 10
}

GET /market/losers/

Free

Get top losing stocks by percentage change.

Query Parameters:

limit — Number of results (default: 10, max: 50)

View Response

json

{
  "losers": [
    {
      "symbol": "9639",
      "name": "شركة أنماط التقنية للتجارة",
      "name_en": "Anmat Technology Trading Co",
      "price": 8.2,
      "change": -0.8,
      "change_percent": -8.89,
      "volume": 9206,
      "updated_at": "2026-01-28T12:10:18+00:00"
    }
  ],
  "count": 10
}

GET /market/volume/

Free

Get top stocks by trading volume.

Query Parameters:

limit — Number of results (default: 10, max: 50)

View Response

json

{
  "stocks": [
    {
      "symbol": "2222",
      "name": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 25.64,
      "change": 0.38,
      "change_percent": 1.5,
      "volume": 15738067,
      "updated_at": "2026-01-28T12:19:48+00:00"
    }
  ],
  "count": 10
}

GET /market/value/

Free

Get top stocks by trading value (SAR).

Query Parameters:

limit — Number of results (default: 10, max: 50)

View Response

json

{
  "stocks": [
    {
      "symbol": "2222",
      "name": "أرامكو السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 25.64,
      "change": 0.38,
      "change_percent": 1.5,
      "volume": 15738067,
      "value": 402108076.72,
      "updated_at": "2026-01-28T12:19:48+00:00"
    }
  ],
  "count": 10
}

GET /market/sectors/

Free

Get sector performance and statistics.

View Response

json

{
  "sectors": [
    {
      "id": "TBNI",
      "name": "Banks",
      "change_percent": 0.45,
      "avg_change_percent": 0.38,
      "volume": 45027873,
      "num_stocks": 10
    }
  ],
  "count": 20
}

Company Info

Get detailed company information including fundamentals, technicals, and valuation data.

GET /company/{symbol}/

Free

Get company information. Response varies by plan.

Data Available by Plan:

Free: Name, sector, industry, description, website
Starter: + Full fundamentals (PE, EPS, book value, beta)
Pro: + Technicals, valuation, analyst targets

View Response (Pro)

json

{
  "symbol": "2222",
  "name": "أرامكو السعودية",
  "name_en": "Saudi Arabian Oil Co",
  "current_price": 25.64,
  "sector": "Energy",
  "industry": "Oil & Gas",
  "description": "Saudi Aramco is the world's largest oil producer...",
  "website": "https://www.aramco.com",
  "country": "Saudi Arabia",
  "currency": "SAR",
  
  "fundamentals": {
    "market_cap": 7500000000000,
    "pe_ratio": 14.2,
    "forward_pe": 12.8,
    "eps": 1.85,
    "book_value": 8.45,
    "price_to_book": 3.03,
    "beta": 0.85,
    "shares_outstanding": 240000000000,
    "float_shares": 3600000000,
    "fifty_two_week_high": 32.5,
    "fifty_two_week_low": 24.1
  },
  
  "technicals": {
    "rsi_14": 55.3,
    "macd_line": 0.12,
    "macd_signal": 0.08,
    "macd_histogram": 0.04,
    "fifty_day_average": 26.1,
    "technical_strength": 0.65,
    "price_direction": "bullish",
    "updated_at": "2026-01-28T10:00:00+03:00"
  },
  
  "valuation": {
    "fair_price": 28.50,
    "fair_price_confidence": 0.85,
    "calculated_at": "2026-01-28T10:00:00+03:00"
  },
  
  "analysts": {
    "target_mean": 29.5,
    "target_median": 29.0,
    "target_high": 35.0,
    "target_low": 24.0,
    "recommendation": "buy",
    "recommendation_score": 2.1,
    "num_analysts": 15
  }
}

Historical Data

Access historical OHLCV (Open, High, Low, Close, Volume) data for technical analysis and backtesting.

GET /historical/{symbol}/

Starter+

Get historical price data for a stock.

Query Parameters:

from — Start date YYYY-MM-DD (default: 30 days ago)
to — End date YYYY-MM-DD (default: today)
interval — Data interval: 1d, 1w, 1m (default: 1d)

View Response

json

{
  "symbol": "2222",
  "interval": "1d",
  "from": "2026-01-01",
  "to": "2026-01-28",
  "count": 20,
  "data": [
    {
      "date": "2026-01-28",
      "open": 25.3,
      "high": 25.68,
      "low": 25.3,
      "close": 25.64,
      "volume": 15738067,
      "adjusted_close": 25.64,
      "turnover": 402108076.72
    }
  ]
}

Financials

Access financial statements including income statements, balance sheets, and cash flow data.

GET /financials/{symbol}/

Starter+

Get financial statements for a company.

View Response

json

{
  "symbol": "2222",
  "income_statements": [
    {
      "report_date": "2025-09-30",
      "total_revenue": 418116750000.0,
      "gross_profit": 215000000000.0,
      "operating_income": 180000000000.0,
      "net_income": 105000000000.0
    }
  ],
  "balance_sheets": [
    {
      "report_date": "2025-09-30",
      "total_assets": 2516431000000.0,
      "total_liabilities": 1026431000000.0,
      "stockholders_equity": 1490000000000.0,
      "total_debt": 356540000000.0
    }
  ],
  "cash_flows": [
    {
      "report_date": "2025-09-30",
      "operating_cash_flow": 135375000000.0,
      "investing_cash_flow": -45000000000.0,
      "financing_cash_flow": -82337000000.0,
      "free_cash_flow": 88500000000.0
    }
  ]
}

Dividends

Get dividend history, upcoming distributions, and trailing yield for a stock.

GET /dividends/{symbol}/

Starter+

Get dividend history and yield information.

View Response

json

{
  "symbol": "2222",
  "current_price": 25.64,
  "trailing_12m_yield": 4.2,
  "trailing_12m_dividends": 1.60,
  "payments_last_year": 4,
  "upcoming": [
    {
      "value": 0.40,
      "period": "Q4",
      "eligibility_date": "2026-03-15",
      "distribution_date": "2026-04-01"
    }
  ],
  "history": [
    {
      "value": 0.40,
      "value_percent": 1.5,
      "period": "Q3",
      "fiscal_year": 2025,
      "announcement_date": "2025-09-01",
      "eligibility_date": "2025-09-15",
      "distribution_date": "2025-10-01"
    }
  ]
}

Stock Events

Get AI-generated summaries of significant stock events and news (Arabic only).

GET /events/

Pro+

Get stock events with AI-generated analysis.

Query Parameters:

symbol — Filter by stock ticker (optional)
limit — Number of results (default: 20)

Note: Event descriptions are in Arabic only. Event types are UPPERCASE (e.g., FINANCIAL_REPORT, DIVIDEND_ANNOUNCEMENT).

View Response

json

{
  "events": [
    {
      "symbol": "4190",
      "stock_name": "جرير للتسويق",
      "event_type": "FINANCIAL_REPORT",
      "importance": "important",
      "sentiment": "positive",
      "description": "شركة جرير للتسويق تعلن عن نتائج مالية قياسية للربع الرابع 2025...",
      "article_date": "2026-01-29T17:10:06+00:00",
      "created_at": "2026-01-29T17:10:12+00:00"
    }
  ],
  "count": 1,
  "available_types": [
    "FINANCIAL_REPORT", "DIVIDEND_ANNOUNCEMENT", "STOCK_SPLIT",
    "MERGER_ACQUISITION", "MANAGEMENT_CHANGE", "NEW_LISTING",
    "REGULATORY_ACTION", "PARTNERSHIP", "MARKET_EXPANSION",
    "RESTRUCTURING", "EARNINGS_SURPRISE", "PRODUCT_LAUNCH", "OTHER"
  ]
}

importance: critical, important, regular

sentiment: very_positive, positive, slightly_positive, neutral, slightly_negative, negative, very_negative

Rate Limits

API access is rate-limited based on your subscription plan. There are two types of limits: daily quotas and per-minute burst limits.

Plan Limits

Plan	Daily Limit	Burst Limit	API Keys
Free	100/day	10/min	1
Starter	5,000/day	100/min	3
Pro	50,000/day	500/min	10
Enterprise	Unlimited	2,000/min	Unlimited

Burst Protection: To prevent abuse, all plans have per-minute burst limits. Requests exceeding the burst limit will receive a 429 response. Daily limits reset at midnight (UTC+3).

Rate Limit Headers

Each response includes headers to help track your usage:

http

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 2026-01-30T00:00:00+03:00

Error Codes

The API uses standard HTTP status codes and returns structured JSON error responses.

401INVALID_API_KEY

API key is missing, invalid, or revoked.

403PLAN_LIMIT

Endpoint requires a higher plan (e.g., historical data requires Starter+).

404INVALID_SYMBOL

Stock symbol not found in TASI or Nomu.

429RATE_LIMIT

Daily quota or per-minute burst limit exceeded.

500SERVER_ERROR

Internal server error. Please retry or contact support.

Error Response Format

json

{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Daily request limit exceeded. Resets at midnight UTC+3."
  }
}

Need More Help?

Check the machine-readable docs at /api-docs.md or contact our team.