SouqData API

Name: GCC Corporate Governance Dataset
Creator: SouqData
License: https://creativecommons.org/licenses/by-nc/4.0/

Programmatic access to GCC stock market data, governance analytics, and Islamic finance screening. 1,937 companies across 11 exchanges, 106 analytics engines, and an AI copilot with 131 tools -- all via REST.

REST / JSON11 Exchanges1,937 Companies106 Engines131 Copilot ToolsUBO & PEPShariah Screening

Interactive API Reference (Swagger UI) →

Quick Start

1
Get an API key
Sign up at /pricing and generate a key from your account dashboard. The free tier includes 10 requests per day.
2
Make your first request
Pass your key in the x-api-key header. All endpoints return JSON with a data wrapper.
```
curl "https://souqdata.com/api/v1/companies?q=emaar" \
  -H "x-api-key: YOUR_API_KEY"
```
3
Explore the endpoints
Browse the endpoint reference below. Every analytics engine available on the website is also accessible via the API.

Authentication

Authenticate requests by passing your API key in the x-api-key HTTP header.

GET /api/v1/companies HTTP/1.1
Host: souqdata.com
x-api-key: gxp_live_a1b2c3d4e5f6...

Unauthenticated requests are treated as free-tier with a limit of 10 requests per day. To increase your limit, include a valid API key.

Keep your key secret. Never expose it in client-side code, public repositories, or browser requests. If compromised, rotate it immediately from your account dashboard.

Response Format

All responses return JSON. Successful responses wrap the payload in a data field. Some endpoints include an additional meta field with counts, methodology notes, or pagination info.

Success (200)

{
  "data": { ... },
  "meta": { "count": 42 }
}

Error (4xx / 5xx)

{
  "error": "Company XYZ not found"
}

Responses include Cache-Control headers. Most data endpoints cache for 5 minutes; director and officer data caches for 1 hour.

Endpoint Reference

GET/api/v1/companies

List Companies

Returns all active GCC-listed companies. Optionally filter by search query or GICS sector.

Parameters

Name	Type	Required	Description
q	string	Optional	Search by company name or ticker
sector	string	Optional	Filter by GICS sector (e.g. "Financials", "Real Estate")

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "ticker": "EMAAR",
      "company_name": "Emaar Properties PJSC",
      "company_name_ar": "\u0625\u0639\u0645\u0627\u0631 \u0627\u0644\u0639\u0642\u0627\u0631\u064a\u0629",
      "gics_sector": "Real Estate",
      "exchange_code": "DFM",
      "market_cap_usd": 18200000000,
      "is_shariah_compliant": true
    }
  ],
  "meta": { "count": 1300 }
}

GET/api/v1/companies/{ticker}

Company Detail

Full company profile including financials, directors, dividends, and key metrics.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol (e.g. "EMAAR", "QNB")

Example Response

{
  "data": {
    "issuer": {
      "ticker": "EMAAR",
      "company_name": "Emaar Properties PJSC",
      "gics_sector": "Real Estate",
      "market_cap_usd": 18200000000,
      "reporting_currency": "AED"
    },
    "directors": [...],
    "financials": [...],
    "dividends": [...],
    "metrics": [...]
  }
}

GET/api/v1/screener

Screener

Query the denormalized screener view with filters, sorting, and market cap ranges. Returns all 212+ columns from v_screener.

Parameters

Name	Type	Required	Description
sector	string	Optional	Filter by GICS sector
sort	string	Optional	Column to sort by (default: "market_cap_usd")
dir	"asc" \| "desc"	Optional	Sort direction (default: "desc")
min_mcap	integer	Optional	Minimum market cap in USD
max_mcap	integer	Optional	Maximum market cap in USD

Example Response

{
  "data": [
    {
      "ticker": "QNB",
      "company_name": "QNB Group",
      "gics_sector": "Financials",
      "market_cap_usd": 45000000000,
      "pe_ratio": 9.2,
      "dividend_yield_pct": 3.8,
      "roe_pct": 18.5,
      "islamic_debt_ratio": 0.12,
      ...
    }
  ],
  "meta": { "count": 1300 }
}

GET/api/v1/directors

Directors

Search directors by name (English or Arabic) or list current board members for a specific company.

Parameters

Name	Type	Required	Description
q	string	Optional	Search by director name (supports English and Arabic, e.g. "Mohammed" or "محمد")
ticker	string	Optional	List directors for a specific company
limit	integer	Optional	Max results (default: 50, max: 200)

Example Response

{
  "data": [
    {
      "id": "d1e2f3...",
      "full_name": "Mohamed Alabbar",
      "gender": "male",
      "nationality": "UAE",
      "biography": "...",
      "director": {
        "role": "Chairman",
        "is_independent": false,
        "is_chair": true
      }
    }
  ]
}

GET/api/v1/officers/{ticker}

Officers

Combined board members and executive management for a company. Includes permanent person IDs for cross-referencing.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol
type	"board" \| "executive"	Optional	Filter by officer type
status	"current" \| "former"	Optional	Filter by appointment status
from	date	Optional	Appointed after this date (YYYY-MM-DD)
to	date	Optional	Appointed before this date (YYYY-MM-DD)

Example Response

{
  "data": {
    "ticker": "EMAAR",
    "company_name": "Emaar Properties PJSC",
    "officers": [
      {
        "name": "Mohamed Alabbar",
        "type": "board",
        "role": "Chairman",
        "is_current": true,
        "appointed_date": "2017-04-20",
        "is_independent": false,
        "permanent_id": "p-abc123"
      }
    ],
    "total_count": 14,
    "current_count": 9
  }
}

GET/api/v1/fair-value/{ticker}

Fair Value Estimate

Three-model valuation: DCF (discounted cash flow), DDM (dividend discount model), and EV/EBITDA relative valuation. Returns consensus estimate and upside/downside percentage.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol

Example Response

{
  "data": {
    "ticker": "EMAAR",
    "current_price": 8.45,
    "currency": "AED",
    "consensus_fair_value": 10.20,
    "upside_pct": 20.7,
    "models": {
      "dcf": { "value": 11.30, "confidence": "medium" },
      "ddm": { "value": 9.80, "confidence": "high" },
      "ev_ebitda": { "value": 9.50, "confidence": "medium" }
    }
  }
}

GET/api/v1/dividend-safety/{ticker}

Dividend Safety Score

Composite dividend safety assessment based on payout ratio, coverage, streak, DPS trend, and earnings stability.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol

Example Response

{
  "data": {
    "ticker": "EMAAR",
    "company_name": "Emaar Properties PJSC",
    "score": 72,
    "grade": "B+",
    "is_reit": false,
    "dividend_yield_pct": 3.5,
    "dps_local": 0.30,
    "payout_ratio_pct": 38.2,
    "streak_years": 5,
    "components": {
      "payout_ratio": { "score": 85, "weight": 0.25 },
      "coverage": { "score": 78, "weight": 0.20 },
      "streak": { "score": 60, "weight": 0.20 },
      "dps_trend": { "score": 65, "weight": 0.20 },
      "earnings_stability": { "score": 72, "weight": 0.15 }
    }
  }
}

GET/api/v1/accounting-quality/{ticker}

Accounting Quality

Forensic accounting analysis using Beneish M-Score, Sloan Accruals Ratio, and a composite quality score. Flags earnings manipulation risk.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol

Example Response

{
  "data": {
    "ticker": "EMAAR",
    "m_score": -2.45,
    "m_score_flag": "unlikely_manipulator",
    "accruals_ratio": 0.03,
    "accruals_flag": "low_risk",
    "composite_score": 78,
    "grade": "B+",
    "components": { ... }
  },
  "meta": {
    "methodology": "Beneish M-Score + Sloan Accruals Ratio + Composite Quality Score"
  }
}

GET/api/v1/financial-distress/{ticker}

Financial Distress

Bankruptcy probability using Altman Z-Score (original and adjusted) and Piotroski F-Score. REITs are excluded from Z-Score due to structural leverage.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol

Example Response

{
  "data": {
    "ticker": "EMAAR",
    "altman_z": 2.85,
    "altman_z_zone": "safe",
    "altman_z_adjusted": 3.10,
    "piotroski_f": 7,
    "piotroski_grade": "Strong"
  },
  "meta": {
    "models": ["altman_z", "altman_z_adjusted", "piotroski_f"]
  }
}

GET/api/v1/degrees-of-separation

Degrees of Separation

Find the shortest board network path between two directors using BFS across shared board seats. Max depth: 6.

Parameters

Name	Type	Required	Description
from	uuid	Required	Source director ID
to	uuid	Required	Target director ID

Example Response

{
  "data": {
    "from": "d1e2f3...",
    "to": "a4b5c6...",
    "connected": true,
    "degrees": 2,
    "path": [
      { "person_id": "d1e2f3...", "person_name": "Mohamed Alabbar", "company_ticker": null },
      { "person_id": "x7y8z9...", "person_name": "Ahmad Al Falasi", "company_ticker": "EMAAR" },
      { "person_id": "a4b5c6...", "person_name": "Khalid Al Tayer", "company_ticker": "DFM" }
    ],
    "shared_companies": []
  }
}

GET/api/v1/ubo/{ticker}

UBO Analysis

Trace ownership chains through nominees, custodians, and holding companies to identify ultimate beneficial owners. Returns transparency rating, risk score, and ownership chain.

Parameters

Name	Type	Required	Description
ticker	string	Required	Company ticker symbol (e.g. "EMAAR", "QNB")

Example Response

{
  "data": {
    "ticker": "EMAAR",
    "company_name": "Emaar Properties PJSC",
    "overall_risk_score": 35,
    "ownership_transparency_rating": "Partially Transparent",
    "beneficial_owners": [
      {
        "name": "Investment Corporation of Dubai",
        "type": "government",
        "ownership_pct": 29.2,
        "is_pep": true,
        "confidence": "high"
      }
    ],
    "ownership_chains": [...],
    "risk_flags": ["nominee_concentration > 20%"]
  }
}

GET/api/v1/pep-check/{slug}

PEP Screening

Screen a person for Politically Exposed Person status using FATF R12 criteria adapted for GCC markets. Checks ruling family membership, SWF representation, government appointments, regulatory positions, and merchant family connections.

Parameters

Name	Type	Required	Description
slug	string	Required	Person slug (URL-safe name, e.g. "khalid-al-falih")

Example Response

{
  "data": {
    "full_name": "Khalid Al-Falih",
    "is_pep": true,
    "risk_level": "high",
    "categories": ["government_appointee", "state_enterprise"],
    "reasons": [
      {
        "category": "government_appointee",
        "description": "Former Minister of Energy",
        "confidence": "confirmed"
      }
    ],
    "current_roles": [...]
  }
}

POST/api/v1/ask

AI Copilot

Natural language query interface powered by Claude Sonnet 4. Streams responses via Server-Sent Events (SSE). Supports multi-round tool calling with ${PLATFORM.copilotTools} data tools.

Parameters

Name	Type	Required	Description
query	string	Required	Natural language question (in request body JSON)

Example Response

// SSE stream
data: {"type":"text","content":"Emaar Properties (DFM: EMAAR) is..."}
data: {"type":"text","content":" the largest real estate developer..."}
data: {"type":"done"}

POST/api/v1/mcp

MCP Server

Model Context Protocol (JSON-RPC 2.0) server with ${PLATFORM.copilotTools} tools. Compatible with Claude Desktop and Claude Code. GET returns server info and tool count.

Parameters

Name	Type	Required	Description
jsonrpc	string	Required	"2.0"
method	string	Required	MCP method (e.g. "tools/list", "tools/call")
params	object	Optional	Method-specific parameters
id	string \| number	Required	Request ID

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_companies",
        "description": "Search GCC-listed companies by name or ticker",
        "inputSchema": { ... }
      },
      ...
    ]
  }
}

Rate Limits

Rate limits are enforced per API key on a rolling 24-hour window. When you exceed your limit, the API returns 429 Too Many Requests.

Tier	Requests / Day	Price
Free	10 / day	Free
Pro	60 / day	$49/mo
EnterpriseRecommended	300 / day	$199/mo
Institutional	1,250 / day	Custom

Need higher limits? View pricing plans or contact us for a custom arrangement.

Code Examples

curl -s "https://souqdata.com/api/v1/companies?sector=Financials" \
  -H "x-api-key: YOUR_API_KEY" | jq .

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://souqdata.com/api/v1"

# List financial-sector companies
resp = requests.get(
    f"{BASE}/companies",
    headers={"x-api-key": API_KEY},
    params={"sector": "Financials"},
)
companies = resp.json()["data"]

# Get fair value for each
for company in companies[:5]:
    ticker = company["ticker"]
    fv = requests.get(
        f"{BASE}/fair-value/{ticker}",
        headers={"x-api-key": API_KEY},
    ).json()["data"]
    print(f"{ticker}: {fv['consensus_fair_value']} {fv['currency']}")

const API_KEY = "YOUR_API_KEY";
const BASE = "https://souqdata.com/api/v1";

async function getCompanies(sector?: string) {
  const url = new URL(`${BASE}/companies`);
  if (sector) url.searchParams.set("sector", sector);

  const res = await fetch(url, {
    headers: { "x-api-key": API_KEY },
  });

  if (!res.ok) throw new Error(`${res.status}: ${res.statusText}`);
  return res.json();
}

async function getFairValue(ticker: string) {
  const res = await fetch(`${BASE}/fair-value/${ticker}`, {
    headers: { "x-api-key": API_KEY },
  });
  return res.json();
}

// Usage
const { data } = await getCompanies("Real Estate");
for (const company of data.slice(0, 5)) {
  const fv = await getFairValue(company.ticker);
  console.log(`${company.ticker}: ${fv.data.consensus_fair_value}`);
}

MCP Integration

SouqData exposes a Model Context Protocol (MCP) server at /api/v1/mcp. This lets AI assistants like Claude Desktop and Claude Code query GCC market data directly.

The MCP server provides 131 tools covering company search, financials, directors, governance scores, Shariah compliance, fair value estimates, UBO analysis, PEP screening, and stock screening. Configure it in your Claude Desktop settings:

{
  "mcpServers": {
    "souqdata": {
      "url": "https://souqdata.com/api/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

MCP access requires an Enterprise or Institutional plan.

Endpoint Index

GET/api/v1/companies GET/api/v1/companies/{ticker}GET/api/v1/screener GET/api/v1/directors GET/api/v1/officers/{ticker}GET/api/v1/fair-value/{ticker}GET/api/v1/dividend-safety/{ticker}GET/api/v1/accounting-quality/{ticker}GET/api/v1/financial-distress/{ticker}GET/api/v1/degrees-of-separation GET/api/v1/ubo/{ticker}GET/api/v1/pep-check/{slug}POST/api/v1/ask POST/api/v1/mcp

Webhooks

Register webhook URLs to receive real-time notifications when data changes. Available on Enterprise and Institutional plans.

Event	Description
announcement.new	New exchange announcement published
price.update	Stock price updated (delayed 15min)
governance.change	Governance score changed by 10+ points
insider.trade	New insider trade reported
shariah.change	Shariah compliance status changed
consensus.change	Analyst consensus rating upgraded/downgraded

POST /api/v1/webhooks
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-app.com/hooks/souqdata",
  "events": ["announcement.new", "governance.change"],
  "tickers": ["2222", "EMAAR"]  // optional: filter by ticker
}

Coming soon. Webhook delivery is in private beta. Contact hello@souqdata.com for early access.

Changelog

v1.5.0

2026-04-08

+ Semantic search API with 22,920 embedded announcements
+ Company Financials tab UX overhaul (IS/BS/CF multi-year)
+ Royal & political influence layer (234 royal directors, 30 SWF reps)
+ Power map page with sovereign links

v1.4.0

2026-04-06

+ Broker flow intelligence (495 records, 34 Tadawul members)
+ Saudi IR Toolkit (disclosure timeliness, blackout violations, foreign ownership)
+ QSE data enrichment (16,609 announcements, 116K+ prices backfilled)
+ Chair-CEO Language Intelligence Scores

v1.3.0

2026-03-28

+ 126 copilot tools for AI-powered analysis
+ Deep research with bilingual (EN/AR) support
+ Governance badge API (SVG, CORS-enabled)
+ XLSX screener export

v1.2.0

2026-03-20

+ Portfolio tracker (6 features: holdings, governance, dividends, Shariah, Zakat)
+ Signal fusion orchestrator (18 rules)
+ Fair value estimation engine (DCF + DDM + EV/EBITDA)

v1.0.0

2026-03-10

+ Initial API release with 55 endpoints
+ OpenAPI 3.0 specification
+ 1,937 companies across 11 exchanges
+ Shariah screening (100% coverage)

Ready to build with GCC market data?

Get started with the free tier (10 requests/day) or upgrade for full API access, AI copilot, and MCP integration.

View Pricing